Skip to main content
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: 
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

Option 1: Homebrew (Recommended)
brew install go
Option 2: Download from golang.org
  1. Go to https://go.dev/dl/
  2. Download the macOS installer (.pkg file)
  3. Run the installer
After installing Go, verify it works: 
go version
Go Version Requirements: The Mizu CLI requires Go 1.22 or later. If you have an older version, please upgrade.

​
Install the Mizu CLI

Now you’re ready to install the Mizu CLI. The easiest way is using go install: 
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: 
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.
Add this line to your ~/.bashrc or ~/.bash_profile:
export PATH="$PATH:$(go env GOPATH)/bin"
Then reload your shell:
source ~/.bashrc

​
Verify Installation

After installation, verify the CLI is working: 
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): 
# 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: 
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: 
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.
Add to your ~/.bashrc:
complete -W "new dev contract version" mizu

​
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: 
    go env GOPATH
  2. Check if the binary exists: 
    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: 
    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) 
sudo go install github.com/go-mizu/mizu/cmd/mizu@latest
Option 2: Set GOPATH to a directory you own (recommended) 
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: 
    go version
  2. Clear Go’s module cache and try again: 
    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: 
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:

Create a Project

Use mizu new to scaffold your first application

Choose a Template

Learn about the different project templates