> ## 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. # Dev > Run your Mizu project in development mode 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 ```bash theme={null} 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 | Flag | Description | | -------------- | --------------------------------- | | `--cmd ` | 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` ```bash theme={null} 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//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: ```bash theme={null} # 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: ```bash theme={null} 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: ```bash theme={null} mizu dev --json ``` This outputs one JSON object per line (NDJSON format): ```json theme={null} {"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 ```json theme={null} { "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: ```bash theme={null} 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`: | 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: ```bash theme={null} # 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: ```bash theme={null} #!/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: ```bash theme={null} # 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: ```bash theme={null} mizu dev -- --port 3000 ``` (Your application needs to handle the `--port` flag) ## Next Steps Start a new project with mizu new See what templates are available