Skip to main content
The Mizu CLI (Command Line Interface) is a tool that helps you create and run Mizu web applications. If you’ve never used a CLI before, don’t worry - this guide will walk you through everything step by step. A CLI is a program you interact with by typing commands in your terminal (also called command prompt, shell, or console). Instead of clicking buttons in a graphical interface, you type text commands and press Enter. The terminal is the black (or white) window where you type commands - every computer has one built in.

​
What Does the Mizu CLI Do?

The Mizu CLI helps you with two main tasks:
  1. Creating new projects - Instead of creating files and folders manually, the CLI generates a complete project structure for you
  2. Running your application - The CLI can start your web server with a single command
Think of it like a helpful assistant that handles the boring setup work so you can focus on building your application.

​
Quick Start Example

Let’s create your first Mizu application. Open your terminal and run these commands: 
# Step 1: Create a new project
mizu new myapp --template minimal

# Step 2: Go into the project folder
cd myapp

# Step 3: Download dependencies
go mod tidy

# Step 4: Start the server
mizu dev
You should see output like this: 
Starting ./cmd/server...
Now open your browser and go to http://localhost:8080. You’ll see your application running. Press Ctrl+C in the terminal to stop the server.

​
Commands

The Mizu CLI has five commands. Each command does one specific thing, making it easy to remember what to type.
CommandWhat it does
mizu newCreates a new project from a template
mizu devRuns your project in development mode
mizu contractWorks with service contracts (for API projects)
mizu middlewareExplores available middlewares
mizu versionShows the CLI version

​
Getting Help

You can add --help to any command to see what options are available: 
# See all commands
mizu --help

# See options for creating a new project
mizu new --help

# See options for the dev command
mizu dev --help

​
Choosing a Template

When you create a new project with mizu new, you choose a template. Each template gives you a different starting point:
TemplateBest forDifficulty
minimalLearning Mizu, quick experimentsBeginner
apiJSON APIs, backend servicesBeginner
contractMulti-protocol APIs (REST + JSON-RPC)Intermediate
webServer-rendered websites with HTMLIntermediate
liveReal-time apps (chat, dashboards)Intermediate
syncOffline-first apps with data syncAdvanced
Not sure which to pick? Start with minimal to learn the basics, then try api when you want to build a real project. To see all available templates: 
mizu new --list
Output: 
Template    Purpose
api         JSON API service with a recommended layout
contract    Transport-neutral service contract with REST, JSON-RPC, and OpenAPI
live        Real-time interactive app with live views and instant updates
minimal     Smallest runnable Mizu project
sync        Offline-first app with sync, live updates, and reactive state
web         Full-stack web app with views, components, and static assets

​
How the CLI Works

When you run mizu new myapp --template api, here’s what happens:
  1. The CLI reads the template files
  2. It creates the myapp folder
  3. It generates all the project files with your project name filled in
  4. It sets up the correct Go module path
When you run mizu dev, here’s what happens:
  1. The CLI looks for your main package (usually in cmd/ folder)
  2. It compiles and runs your Go code
  3. It watches for Ctrl+C to shut down gracefully

​
Design Philosophy

The Mizu CLI follows these principles:
  • Convention over Configuration - It works with sensible defaults, so you don’t need to configure everything
  • Explicit when needed - You can override any default with flags
  • Machine-friendly - All commands support --json output for scripts and automation
  • Clear errors - When something goes wrong, you get helpful messages explaining how to fix it

​
Next Steps

Installation

Get the Mizu CLI installed on your computer

Create Project

Learn all the options for creating projects

Templates

See what each template includes

Middlewares

Explore 100+ available middlewares