Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

The mizu dev command runs your Mizu application in development mode. It automatically finds your main package, compiles your code, starts your server, and handles shutdown gracefully when you press Ctrl+C. This is the command you’ll use most during development.

​
Basic Usage

mizu dev
That’s it! The command auto-detects your main package and runs it.

​
What Happens When You Run mizu dev

  1. Finds your main package - Looks in cmd/ folder first, then checks the root directory
  2. Compiles your code - Uses go run to build and run
  3. Starts your server - Your application starts running
  4. Waits for shutdown - Listens for Ctrl+C or system signals
  5. Shuts down gracefully - Gives your app time to clean up before exiting
Example output: 
Starting ./cmd/api...
Your server is now running! Open your browser to http://localhost:8080 to see it.

​
How to Stop the Server

Press Ctrl+C in your terminal. You’ll see: 
Received interrupt, shutting down...
The CLI sends a signal to your application, giving it time to:
  • Close database connections
  • Finish processing requests
  • Save any pending data
If your app doesn’t stop within 15 seconds, it’s force-terminated.

​
Flags Reference

FlagDescription
--cmd <path>Specify which main package to run
--jsonOutput lifecycle events as JSON
-h, --helpShow help

​
How Main Package Discovery Works

The CLI finds your main package automatically. Here’s the order it checks:

​
1. If You Specify --cmd

mizu dev --cmd ./cmd/server
Uses exactly what you specify. No auto-detection.

​
2. Look in cmd/ Directory

If you have a cmd/ folder, the CLI looks for main.go files inside subdirectories: 
myapp/
├── cmd/
│   └── api/
│       └── main.go    ← Found! Uses ./cmd/api
└── go.mod

​
3. Check Root Directory

If there’s no cmd/ folder, it checks the current directory: 
myapp/
├── main.go            ← Found! Uses .
└── go.mod

​
When Discovery Fails

If no main package is found: 
error: no runnable main package found (try --cmd)
Fix: Either:
  • Create a cmd/<name>/main.go file
  • Create a main.go in your root directory
  • Use --cmd to point to your main package

​
Working with Multiple Commands

If your project has multiple entry points: 
myapp/
├── cmd/
│   ├── api/
│   │   └── main.go    # The API server
│   └── worker/
│       └── main.go    # A background worker
└── go.mod
You need to specify which one to run: 
# Run the API server
mizu dev --cmd ./cmd/api

# Run the worker
mizu dev --cmd ./cmd/worker

​
Passing Arguments to Your Application

Use -- to separate CLI flags from your application’s arguments: 
mizu dev -- --port 9000 --debug
Everything after -- is passed to your application. Your app will receive --port 9000 --debug as arguments.

​
JSON Output Mode

For scripts and automation, use --json to get machine-readable output: 
mizu dev --json
This outputs one JSON object per line (NDJSON format): 
{"event":"starting","timestamp":"2024-01-15T10:30:00Z","message":"running ./cmd/api"}
{"event":"started","timestamp":"2024-01-15T10:30:01Z","message":"pid 12345"}

​
Lifecycle Events

EventWhen it happens
startingAbout to start your application
startedApplication started (includes process ID)
signalReceived a shutdown signal (Ctrl+C)
timeoutGraceful shutdown took too long
stoppedApplication exited
errorSomething went wrong

​
Event Structure

{
  "event": "started",
  "timestamp": "2024-01-15T10:30:01Z",
  "message": "pid 12345",
  "exit_code": 0
}
  • event - Type of event
  • timestamp - When it happened (UTC, ISO 8601 format)
  • message - Human-readable description
  • exit_code - Only included when application exits

​
Verbose Mode

See more details about what’s happening: 
mizu dev -v
Output: 
discovered main package: ./cmd/api
Starting ./cmd/api...

​
Error Messages and Solutions

​
No Main Package Found

error: no runnable main package found (try --cmd)
Why: The CLI couldn’t find a package main in your project. Fix:
  1. Make sure you’re in the right directory
  2. Check that your main.go file has package main at the top
  3. Use --cmd to specify the path manually

​
Path Does Not Exist

error: path does not exist: ./cmd/missing
Why: You specified a --cmd path that doesn’t exist. Fix: Check the path and make sure it’s correct.

​
Build Errors

If your Go code has errors, you’ll see the compiler output: 
Starting ./cmd/api...
# github.com/example/myapp/cmd/api
./main.go:10:5: undefined: mizu
Fix: Fix the Go compilation errors shown.

​
Exit Codes

The exit code from your application passes through mizu dev:
CodeMeaning
0Success - your app exited cleanly
1Error during startup
2Invalid flags or arguments
3No main package found
OtherPassed through from your application
If your app exits with code 5, mizu dev also exits with code 5. This is important for scripts that check exit codes.

​
Development Workflow

A typical development workflow: 
# Terminal 1: Run the server
cd myapp
mizu dev

# Terminal 2: Test your API
curl http://localhost:8080/health

# When you make changes:
# 1. Press Ctrl+C in Terminal 1
# 2. Run: mizu dev again
mizu dev does not watch for file changes. When you modify your code, stop the server with Ctrl+C and restart it.
For the best experience with mizu dev, use this structure: 
myapp/
├── cmd/
│   └── api/
│       └── main.go     # Entry point
├── app/
│   └── api/
│       ├── app.go      # Application setup
│       ├── config.go   # Configuration
│       └── routes.go   # Route definitions
├── feature/
│   └── users/
│       └── http.go     # Feature handlers
├── go.mod
└── go.sum
With this structure:
  • mizu dev finds ./cmd/api automatically
  • Code is organized by feature
  • Clear separation of concerns

​
Using with Scripts

Check if the server started successfully: 
#!/bin/bash

# Start server in background, capture output
mizu dev --json &
SERVER_PID=$!

# Wait for started event
sleep 2

# Check if process is still running
if ps -p $SERVER_PID > /dev/null; then
    echo "Server started successfully"
else
    echo "Server failed to start"
    exit 1
fi

# Run your tests here...

# Clean up
kill $SERVER_PID

​
Common Questions

​
Why doesn’t mizu dev watch for file changes?

File watching adds complexity and dependencies. For now, just restart manually. Many editors have built-in run commands that make this easy.

​
Can I run multiple servers at once?

Yes! Open multiple terminals: 
# Terminal 1
mizu dev --cmd ./cmd/api

# Terminal 2
mizu dev --cmd ./cmd/worker

​
How do I change the port?

Configure the port in your application code or use arguments: 
mizu dev -- --port 3000
(Your application needs to handle the --port flag)

​
Next Steps

Create a Project

Start a new project with mizu new

View Templates

See what templates are available