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
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:
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...
- 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
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)
- 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
# 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
-- 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:
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 eventtimestamp - When it happened (UTC, ISO 8601 format)message - Human-readable descriptionexit_code - Only included when application exits
Verbose Mode
See more details about what’s happening:
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)
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
--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
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
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:
(Your application needs to handle the --port flag)
Next Steps