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

# Installation

> Step-by-step guide to install the Mizu CLI on macOS, Linux, and Windows

This guide will help you install the Mizu CLI on your computer. We'll cover everything from checking prerequisites to verifying your installation works. Even if you've never installed a command-line tool before, you'll be able to follow along.

## Prerequisites

Before installing the Mizu CLI, you need Go installed on your computer.

### What is Go?

Go (also called Golang) is the programming language that Mizu is built with. The Mizu CLI is a Go program, so you need Go to install and run it.

### Check if Go is Installed

Open your terminal and run:

```bash theme={null}
go version
```

If Go is installed, you'll see something like:

```
go version go1.23.0 darwin/arm64
```

If you see "command not found", you need to install Go first.

### Install Go

<Tabs>
  <Tab title="macOS">
    **Option 1: Homebrew (Recommended)**

    ```bash theme={null}
    brew install go
    ```

    **Option 2: Download from golang.org**

    1. Go to [https://go.dev/dl/](https://go.dev/dl/)
    2. Download the macOS installer (.pkg file)
    3. Run the installer
  </Tab>

  <Tab title="Linux">
    **Ubuntu/Debian:**

    ```bash theme={null}
    sudo apt update
    sudo apt install golang-go
    ```

    **Fedora:**

    ```bash theme={null}
    sudo dnf install golang
    ```

    **Or download from golang.org:**

    ```bash theme={null}
    # Download (check go.dev for latest version)
    wget https://go.dev/dl/go1.23.0.linux-amd64.tar.gz

    # Extract to /usr/local
    sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz

    # Add to PATH (add this to ~/.bashrc or ~/.zshrc)
    export PATH=$PATH:/usr/local/go/bin
    ```
  </Tab>

  <Tab title="Windows">
    1. Go to [https://go.dev/dl/](https://go.dev/dl/)
    2. Download the Windows installer (.msi file)
    3. Run the installer
    4. Restart your terminal/command prompt
  </Tab>
</Tabs>

After installing Go, verify it works:

```bash theme={null}
go version
```

<Note>
  **Go Version Requirements:** The Mizu CLI requires Go 1.22 or later. If you have an older version, please upgrade.
</Note>

## Install the Mizu CLI

Now you're ready to install the Mizu CLI. The easiest way is using `go install`:

```bash theme={null}
go install github.com/go-mizu/mizu/cmd/mizu@latest
```

This command:

1. Downloads the Mizu CLI source code
2. Compiles it on your computer
3. Installs the `mizu` binary to your Go bin directory

### Where is the Binary Installed?

The `mizu` binary is installed to `$GOPATH/bin`. You can find this location by running:

```bash theme={null}
go env GOPATH
```

This will show something like:

* **macOS/Linux:** `/Users/yourname/go` or `/home/yourname/go`
* **Windows:** `C:\Users\yourname\go`

The binary is in the `bin` folder inside that directory.

## Add Go Bin to Your PATH

For the `mizu` command to work from anywhere, the Go bin directory must be in your PATH.

<Tabs>
  <Tab title="macOS/Linux (Bash)">
    Add this line to your `~/.bashrc` or `~/.bash_profile`:

    ```bash theme={null}
    export PATH="$PATH:$(go env GOPATH)/bin"
    ```

    Then reload your shell:

    ```bash theme={null}
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="macOS/Linux (Zsh)">
    Add this line to your `~/.zshrc`:

    ```bash theme={null}
    export PATH="$PATH:$(go env GOPATH)/bin"
    ```

    Then reload your shell:

    ```bash theme={null}
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Windows">
    1. Press `Win + R`, type `sysdm.cpl`, press Enter
    2. Click "Advanced" tab
    3. Click "Environment Variables"
    4. Under "User variables", find "Path" and click "Edit"
    5. Click "New" and add: `%USERPROFILE%\go\bin`
    6. Click "OK" to save
    7. Restart your terminal
  </Tab>
</Tabs>

## Verify Installation

After installation, verify the CLI is working:

```bash theme={null}
mizu version
```

You should see output like:

```
mizu version 0.1.0
go version: go1.23.0
commit: abc1234
built: 2024-01-15T10:30:00Z
```

If you see this, the installation was successful.

## Install from Source

If you want to build from source (for development or to get the latest unreleased changes):

```bash theme={null}
# Clone the repository
git clone https://github.com/go-mizu/mizu.git
cd mizu

# Build the CLI
go build -o mizu ./cmd/mizu

# Move to a directory in your PATH
# macOS/Linux:
sudo mv mizu /usr/local/bin/

# Or move to Go bin:
mv mizu $(go env GOPATH)/bin/
```

### Build with Version Information

For production builds, you can embed version information:

```bash theme={null}
go build -ldflags "\
  -X github.com/go-mizu/mizu/cli.Version=1.0.0 \
  -X github.com/go-mizu/mizu/cli.Commit=$(git rev-parse --short HEAD) \
  -X github.com/go-mizu/mizu/cli.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o mizu ./cmd/mizu
```

## Updating the CLI

To update to the latest version:

```bash theme={null}
go install github.com/go-mizu/mizu/cmd/mizu@latest
```

This downloads and installs the newest version, replacing the old one.

## Shell Completion

You can set up tab completion for command names. This lets you press Tab to autocomplete commands.

<Tabs>
  <Tab title="Bash">
    Add to your `~/.bashrc`:

    ```bash theme={null}
    complete -W "new dev contract version" mizu
    ```
  </Tab>

  <Tab title="Zsh">
    Add to your `~/.zshrc`:

    ```zsh theme={null}
    compctl -k "(new dev contract version)" mizu
    ```
  </Tab>
</Tabs>

## Troubleshooting

### "command not found: mizu"

This means your terminal can't find the `mizu` binary. The most common cause is that Go's bin directory isn't in your PATH.

**Fix:**

1. Check where Go installs binaries:
   ```bash theme={null}
   go env GOPATH
   ```

2. Check if the binary exists:
   ```bash theme={null}
   ls $(go env GOPATH)/bin/mizu
   ```

3. If the binary exists but the command doesn't work, add Go bin to your PATH (see above).

4. After updating PATH, restart your terminal or run:
   ```bash theme={null}
   source ~/.bashrc  # or ~/.zshrc
   ```

### "go: command not found"

Go is not installed or not in your PATH. Follow the Go installation instructions above.

### "permission denied"

If you get permission errors:

**Option 1:** Use sudo (not recommended for go install)

```bash theme={null}
sudo go install github.com/go-mizu/mizu/cmd/mizu@latest
```

**Option 2:** Set GOPATH to a directory you own (recommended)

```bash theme={null}
export GOPATH=$HOME/go
go install github.com/go-mizu/mizu/cmd/mizu@latest
```

### Build Errors

If you get compilation errors when installing:

1. Make sure you have Go 1.22 or later:
   ```bash theme={null}
   go version
   ```

2. Clear Go's module cache and try again:
   ```bash theme={null}
   go clean -modcache
   go install github.com/go-mizu/mizu/cmd/mizu@latest
   ```

### Verify Go Environment

If you're having trouble, check your Go environment:

```bash theme={null}
go env
```

Key variables to check:

* `GOPATH`: Where Go stores packages and binaries
* `GOROOT`: Where Go itself is installed
* `GOBIN`: Where binaries are installed (defaults to `$GOPATH/bin`)

## Next Steps

Now that you have the CLI installed, you're ready to create your first project:

<CardGroup cols={2}>
  <Card title="Create a Project" icon="rocket" href="/cli/new">
    Use mizu new to scaffold your first application
  </Card>

  <Card title="Choose a Template" icon="folder-tree" href="/cli/templates">
    Learn about the different project templates
  </Card>
</CardGroup>