Installation

Pyahu is distributed as a single binary. Releases for macOS, Linux and Windows (amd64 and arm64) are published on GitHub Releases with checksums.txt.

Prerequisites

The CLI orchestrates a local k3d cluster. You need:

• Docker or Podman running
• k3d 5.x on your PATH

The CLI itself does not require kubectl or helm in the normal flow. The pyahu doctor command checks these dependencies before bringing up the stack.

mise

Pinning the CLI next to the rest of a project’s toolchain keeps everyone on the team on the same version, recorded in the repository:

# in a project, resolves latest and writes its exact version to ./mise.toml
mise use --pin "github:pyahu/cli@latest"

# or for your user, everywhere
mise use -g --pin "github:pyahu/cli@latest"

mise install

mise.toml

[tools]
"github:pyahu/cli" = "<resolved-version>"

mise’s github: backend downloads and extracts the matching GitHub release.

Pyahu toolchain

The Pyahu toolchain already pins the CLI in its cloud profile, alongside k3d, kubectl and the rest of the Kubernetes set. If you use the toolchain, you already have the CLI:

export MISE_ENV=cloud    # add this to your shell rc
mise install

Installation script (macOS and Linux)

The script detects the OS and architecture, downloads the release from GitHub, verifies its checksum and installs it to /usr/local/bin:

curl -fsSL https://cli.pyahu.io/install.sh | sh

To install to another directory (without sudo):

curl -fsSL https://cli.pyahu.io/install.sh | sh -s -- --bin-dir "$HOME/.local/bin"

To pin a specific version:

curl -fsSL https://cli.pyahu.io/install.sh | sh -s -- --version v0.10.1

To inspect the script before running it, download or print it first. Its archive check uses the SHA-256 value in the checksums.txt published with the same release. To update, use pyahu upgrade or run the script again.

go install

If you already have Go 1.26+:

go install github.com/pyahu/cli/cmd/pyahu@latest

The binary goes to $(go env GOPATH)/bin. Make sure that directory is on your PATH.

Manual download (GitHub Releases)

Download the archive for your platform from github.com/pyahu/cli/releases and extract the binary:

# Linux x86_64
tar -xzf pyahu_Linux_x86_64.tar.gz
sudo mv pyahu /usr/local/bin/

# macOS arm64
tar -xzf pyahu_Darwin_arm64.tar.gz
sudo mv pyahu /usr/local/bin/

On Windows, extract the .zip and add pyahu.exe to your PATH.

Staying up to date

The CLI warns when it is behind a release. To check on demand and upgrade:

pyahu check-update
pyahu upgrade

upgrade verifies the release’s SHA-256 against the published checksums.txt before swapping the binary. If pyahu was installed by mise (or go install), it leaves the file alone — replacing it would be undone by the next mise install — and prints the right command instead:

error: this pyahu is managed by another tool; upgrade it with: mise use github:pyahu/cli@<version>

Verify the installation

pyahu --version
pyahu doctor

pyahu doctor reports Docker/Podman, k3d, local ports, and the presence of other local clusters. It warns about conflicts, but does not fail just because another cluster exists.

Shell autocomplete

The CLI generates completion scripts for bash, zsh, fish, and powershell:

# zsh
pyahu completion zsh > "${fpath[1]}/_pyahu"

# bash
pyahu completion bash | sudo tee /etc/bash_completion.d/pyahu > /dev/null

# fish
pyahu completion fish > ~/.config/fish/completions/pyahu.fish

Reopen your shell to load the completion.

Next step

pyahu init --preset platform
pyahu up

See the full walkthrough in Overview.