Skip to main content
The Mizu CLI provides tools for creating projects, running development servers, and managing contracts. It’s the fastest way to start new Mizu projects.

​
What is the Mizu CLI?

The CLI offers:
  • mizu new: Create new projects from templates
  • mizu dev: Run development server with hot reload
  • mizu contract: Generate SDKs and OpenAPI specs
  • mizu version: Show version information
# Create a new API project
mizu new myapi --template api

# Start development server
cd myapi && mizu dev

# Generate TypeScript SDK
mizu contract sdk typescript --output ./sdk

​
Installation

​
Using Go Install

go install github.com/go-mizu/mizu/cmd/mizu@latest
Ensure $GOPATH/bin is in your PATH: 
export PATH="$PATH:$(go env GOPATH)/bin"

​
Verify Installation

mizu version
# mizu version 1.x.x

​
Creating Projects

​
Basic Usage

mizu new <project-name> --template <template>

​
Available Templates

TemplateDescriptionUse Case
minimalBasic server with one routeLearning, simple services
apiREST API with validationAPIs, microservices
contractContract-based serviceMulti-transport APIs
webServer-rendered websiteWebsites, blogs
liveReal-time UI updatesDashboards, chat
syncState synchronizationCollaborative apps
frontend:reactReact SPA with Go backendFull-stack apps
frontend:vueVue SPA with Go backendFull-stack apps
frontend:svelteSvelte SPA with Go backendFull-stack apps
mobile:flutterFlutter app backendMobile backends
mobile:reactnativeReact Native backendMobile backends

​
Examples

# Minimal server
mizu new hello --template minimal

# REST API
mizu new userapi --template api

# Contract-based service
mizu new payments --template contract

# Full-stack with React
mizu new dashboard --template frontend:react

# Mobile backend for Flutter
mizu new appbackend --template mobile:flutter

​
Template Options

# Specify output directory
mizu new myapp --template api --output /path/to/projects

# With specific Go module name
mizu new myapp --template api --module github.com/myorg/myapp

# Skip git initialization
mizu new myapp --template api --no-git

​
Development Server

​
Basic Usage

mizu dev
This starts your app with:
  • Automatic recompilation on file changes
  • Fast restart
  • Preserved terminal output

​
Options

# Custom port
mizu dev --port 8080

# Custom entry point
mizu dev --entry ./cmd/server

# Verbose output
mizu dev --verbose

# With frontend proxy
mizu dev --proxy http://localhost:5173

​
With Frontend

For full-stack projects, run both servers: 
# Terminal 1: Frontend dev server
cd web && npm run dev

# Terminal 2: Go dev server with proxy
mizu dev --proxy http://localhost:5173
Or use the Makefile: 
make dev  # Runs both concurrently

​
Contract Operations

​
Generate SDKs

# Generate Go SDK
mizu contract sdk go --output ./sdk/go

# Generate Python SDK
mizu contract sdk python --output ./sdk/python

# Generate TypeScript SDK
mizu contract sdk typescript --output ./sdk/typescript

# Generate Swift SDK (iOS)
mizu contract sdk swift --output ./sdk/swift

# Generate Kotlin SDK (Android)
mizu contract sdk kotlin --output ./sdk/kotlin

​
Generate OpenAPI Spec

mizu contract openapi --output ./openapi.json

​
Contract Options

# Specify package/module name
mizu contract sdk go --package github.com/myorg/client --output ./sdk

# With custom server URL
mizu contract openapi --server https://api.example.com --output ./openapi.json

# From specific service
mizu contract sdk go --service UserService --output ./sdk

​
Project Structure by Template

​
Minimal Template

myapp/
├── main.go
├── go.mod
└── go.sum

​
API Template

myapp/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handlers/
│   │   └── users.go
│   ├── models/
│   │   └── user.go
│   └── middleware/
│       └── auth.go
├── go.mod
├── go.sum
├── Makefile
└── README.md

​
Contract Template

myapp/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── services/
│   │   └── user_service.go
│   └── models/
│       └── user.go
├── api/
│   └── openapi.json
├── go.mod
├── go.sum
├── Makefile
└── README.md

​
Frontend Template (React)

myapp/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   └── handlers/
│       └── api.go
├── web/
│   ├── src/
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── go.mod
├── go.sum
├── Makefile
└── README.md

​
Global Flags

Available for all commands:
FlagDescription
--help, -hShow help
--version, -vShow version
--verboseVerbose output
--jsonOutput as JSON
--no-colorDisable colored output

​
Exit Codes

CodeMeaning
0Success
1General error
2Invalid arguments
3File/directory error
4Network error

​
Common Workflows

​
New API Project

# Create project
mizu new myapi --template api

# Enter directory
cd myapi

# Start development
mizu dev

# Test the API
curl http://localhost:3000/api/health

​
Full-Stack Project

# Create project
mizu new myapp --template frontend:react

# Install frontend dependencies
cd myapp/web && npm install && cd ..

# Start both servers
make dev

# Open in browser
open http://localhost:3000

​
Generate Client SDKs

# In your project directory
mizu contract sdk typescript --output ../frontend/src/api

# Use in frontend
# import { APIClient } from './api';

​
Production Build

# Build frontend
cd web && npm run build && cd ..

# Build Go binary with embedded frontend
go build -o server ./cmd/server

# Run in production
./server

​
Configuration

​
Environment Variables

VariableDescriptionDefault
MIZU_PORTDefault port3000
MIZU_ENVEnvironmentdevelopment
MIZU_LOG_LEVELLog levelinfo

​
Config File

Create .mizu.yaml in your project: 
dev:
  port: 8080
  entry: ./cmd/server
  proxy: http://localhost:5173

contract:
  output: ./sdk
  package: github.com/myorg/client

​
Learn More

CLI Documentation

Complete CLI reference.

Templates

All available templates.

​
Next Steps

Build Your First API

Step-by-step tutorial.

Quick Start

Get started without CLI.