Dev - 💧 Mizu

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`

Finds your main package - Looks in cmd/ folder first, then checks the root directory
Compiles your code - Uses go run to build and run
Starts your server - Your application starts running
Waits for shutdown - Listens for Ctrl+C or system signals
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

Flag	Description
`--cmd <path>`	Specify which main package to run
`--json`	Output lifecycle events as JSON
`-h, --help`	Show 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

Event	When it happens
`starting`	About to start your application
`started`	Application started (includes process ID)
`signal`	Received a shutdown signal (Ctrl+C)
`timeout`	Graceful shutdown took too long
`stopped`	Application exited
`error`	Something 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:

Make sure you’re in the right directory
Check that your main.go file has package main at the top
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:

Code	Meaning
0	Success - your app exited cleanly
1	Error during startup
2	Invalid flags or arguments
3	No main package found
Other	Passed 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.

Recommended Project Structure

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

​Basic Usage

​What Happens When You Run mizu dev

​How to Stop the Server

​Flags Reference

​How Main Package Discovery Works

​1. If You Specify --cmd

​2. Look in cmd/ Directory

​3. Check Root Directory

​When Discovery Fails

​Working with Multiple Commands

​Passing Arguments to Your Application

​JSON Output Mode

​Lifecycle Events

​Event Structure

​Verbose Mode

​Error Messages and Solutions

​No Main Package Found

​Path Does Not Exist

​Build Errors

​Exit Codes

​Development Workflow

​Recommended Project Structure

​Using with Scripts

​Common Questions

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

​Can I run multiple servers at once?

​How do I change the port?

​Next Steps

Create a Project

View Templates

Basic Usage

What Happens When You Run `mizu dev`

How to Stop the Server

Flags Reference

How Main Package Discovery Works

1. If You Specify `--cmd`

2. Look in `cmd/` Directory

3. Check Root Directory

When Discovery Fails

Working with Multiple Commands

Passing Arguments to Your Application

JSON Output Mode

Lifecycle Events

Event Structure

Verbose Mode

Error Messages and Solutions

No Main Package Found

Path Does Not Exist

Build Errors

Exit Codes

Development Workflow

Recommended Project Structure

Using with Scripts

Common Questions

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

Can I run multiple servers at once?

How do I change the port?

Next Steps