> ## 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.

# Overview

> Learn what the Mizu CLI is and how it helps you build web applications faster

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:

```bash theme={null}
# 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.

| Command           | What it does                                    |
| ----------------- | ----------------------------------------------- |
| `mizu new`        | Creates a new project from a template           |
| `mizu dev`        | Runs your project in development mode           |
| `mizu contract`   | Works with service contracts (for API projects) |
| `mizu middleware` | Explores available middlewares                  |
| `mizu version`    | Shows the CLI version                           |

### Getting Help

You can add `--help` to any command to see what options are available:

```bash theme={null}
# 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:

| Template   | Best for                              | Difficulty   |
| ---------- | ------------------------------------- | ------------ |
| `minimal`  | Learning Mizu, quick experiments      | Beginner     |
| `api`      | JSON APIs, backend services           | Beginner     |
| `contract` | Multi-protocol APIs (REST + JSON-RPC) | Intermediate |
| `web`      | Server-rendered websites with HTML    | Intermediate |
| `live`     | Real-time apps (chat, dashboards)     | Intermediate |
| `sync`     | Offline-first apps with data sync     | Advanced     |

**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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Get the Mizu CLI installed on your computer
  </Card>

  <Card title="Create Project" icon="rocket" href="/cli/new">
    Learn all the options for creating projects
  </Card>

  <Card title="Templates" icon="folder-tree" href="/cli/templates">
    See what each template includes
  </Card>

  <Card title="Middlewares" icon="layer-group" href="/cli/middleware">
    Explore 100+ available middlewares
  </Card>
</CardGroup>