CLI reference

One binary, a handful of verbs. VM lifecycle on top, cluster and registry management below. Every command and flag here is taken straight from the binary's own help text.

Global usage

Persistent flags apply to every command. --config (short -c) points at an alternate config file; it defaults to ~/.klimax/config.yaml.

$ klimax [-c ~/.klimax/config.yaml] [--debug] [--lima-log-level <level>] <command>

Flag	Description
`-c`, `--config <path>`	Path to the klimax config file (default `~/.klimax/config.yaml`).
`--debug`	Enable klimax debug logging — and surface Lima's own logs at `info`.
`--lima-log-level <level>`	Show the embedded Lima VM logs at this level: `trace`, `debug`, `info`, `warn`, `error`, or `off`. Hidden by default.

📖

This page is a curated summary. For the authoritative, always-current flag list run klimax <command> --help — the binary is the source of truth.

Logging

klimax's own output uses Go's log/slog; the embedded Lima library logs through logrus. By default klimax quiets Lima to error, so you see klimax's messages plus any genuine Lima errors — the noisy INFO[…]/WARN[…] Lima lines are hidden. Turn them on when you need to debug the VM itself:

You want…	Run
Default — quiet Lima, klimax only	(nothing — this is the default)
klimax debug + Lima at `info`	`klimax --debug <command>`
Lima at a specific level	`klimax --lima-log-level info <command>`
Full Lima firehose	`klimax --lima-log-level trace <command>`
Silence Lima entirely (panic-only)	`klimax --lima-log-level off <command>`

# See what Lima is doing while the VM comes up
$ klimax --lima-log-level info up

# klimax debug detail, with Lima surfaced at info
$ klimax --debug up

🔎

An explicit --lima-log-level wins over --debug. Levels: trace · debug · info · warn · error · off (none/quiet/silent also work). VM readiness detection is unaffected — the in-VM hostagent keeps its own verbose logs regardless.

VM lifecycle

Command	Description
`klimax up`	Create/start the VM, provision Docker, create kind clusters, set up routing (idempotent).
`klimax down`	Stop the VM — preserves all clusters and registry cache data.
`klimax down --remove-route`	Also remove the macOS host route (requires sudo).
`klimax destroy`	Delete kind clusters, delete the VM, and remove the macOS route.
`klimax status`	Show VM state, clusters, route, and iptables rule presence.
`klimax doctor`	Diagnose issues and print actionable fix commands.
`klimax shell`	Open an interactive SSH session in the klimax VM.
`klimax config edit`	Open the klimax config file in `$EDITOR`.
`klimax version`	Print the klimax version.

# Bring everything up — prompts for sudo once to add the host route
$ klimax up

# Stop the VM but keep clusters and cache
$ klimax down

# Tear it all down: VM, clusters, and the host route (sudo)
$ klimax destroy

⚠

klimax down keeps the host route in place. Use --remove-route (or klimax destroy) to drop it — either requires sudo.

⬆

After upgrading klimax, re-create the VM. Provisioning is baked into the binary, so klimax down/up on an existing VM keeps running the old setup. Run klimax destroy && klimax up once after each brew upgrade --cask klimax — the host-backed image cache survives, so it rebuilds fast.

Docker access

Point your host's docker CLI at the daemon inside the VM, either per-shell with an environment variable or persistently with a Docker context.

Command	Description
`klimax docker-env`	Print the export command to point `DOCKER_HOST` at the klimax VM.
`klimax docker-env --unset`	Print commands to unset the Docker environment.
`klimax docker-context`	Create/switch to the klimax Docker context.
`klimax docker-context --unset`	Switch back to the default Docker context.

# Option A — environment variable, current shell only
$ eval $(klimax docker-env)
$ eval $(klimax docker-env --unset)

# Option B — Docker context, persistent across shells
$ klimax docker-context
$ klimax docker-context --unset

🐳

If DOCKER_HOST is set it overrides the active Docker context — use one or the other.

Clusters

Cluster lifecycle lives entirely under klimax cluster — there is no cluster list in the config file. For declarative, multi-cluster workflows see Fleet management and the Fleet resource.

Command	Description
`klimax cluster create <name>`	Create a new kind cluster in the running VM.
`klimax cluster apply -f <file>`	Create a fleet of clusters from a Fleet manifest (additive; honours `dependsOn`).
`klimax cluster delete [name]`	Delete a kind cluster (interactive picker when no name is given).
`klimax cluster delete -f <file>`	Delete every cluster listed in a Fleet manifest (reverse-dependency order).
`klimax cluster delete -l <selector>`	Delete clusters whose nodes match a label selector.
`klimax cluster list`	List kind clusters running in the VM (filter with `-l <selector>`).
`klimax cluster label <name>`	Add, overwrite, or remove node labels on an existing cluster.
`klimax cluster e2e-test-nginx`	Deploy nginx and curl it via LoadBalancer to verify the cluster end-to-end.
`klimax cluster use` / `merge`	Deprecated — use `kubeconfig env` / `merge` (or `kubeconfig use` to switch context).

`cluster create` flags

Flag	Description
`--region <r>`	`topology.kubernetes.io/region` label (default `europe-west<N>`).
`--zone <z>`	`topology.kubernetes.io/zone` label (default `europe-west<N>-b`).
`-l`, `--label <k=v>`	Extra node label; repeatable. All nodes also get `managed-by=klimax`.

The cluster num (subnet/port slot) is always auto-assigned to the lowest free value. To pin one, use a Fleet manifest's per-cluster num: field.

$ klimax cluster create dev
$ klimax cluster create dev --region us-east1 --zone us-east1-a
$ klimax cluster create dev -l team=search -l env=dev

Fleets — `apply` & `delete -f`

Create or tear down a whole fleet of clusters from one Fleet manifest. apply is additive — it creates the clusters that don't exist yet, in dependsOn order, up to maxParallel at a time — and never mutates running clusters.

Flag	Applies to	Description
`-f`, `--filename <path>`	`apply`, `delete`	Path to a Fleet manifest; `-` reads stdin.
`--dry-run`	`apply`	Validate and print the resolved plan, then exit without creating anything.
`--max-parallel <N>`	`apply`	Override `spec.maxParallel` (concurrent cluster creations).
`-y`, `--yes`	`delete`	Skip the confirmation prompt.

$ klimax cluster apply -f fleet.yaml --dry-run   # preview the plan
$ klimax cluster apply -f fleet.yaml              # create what's missing
$ cat fleet.yaml | klimax cluster apply -f -      # from stdin
$ klimax cluster delete -f fleet.yaml -y          # tear the fleet down

Listing, switching, merging

cluster list takes -o / --output with text (default), json, or yaml, and -l / --selector to filter by a kubectl-style node-label selector.

$ klimax cluster list
$ klimax cluster list -o json
$ klimax cluster list -l env=dev                    # filter by label selector
$ klimax cluster list -l klimax.dev/fleet=dev-fleet

Pointing kubectl at a cluster now lives under klimax kubeconfig:

# Use one cluster's isolated kubeconfig in this shell
$ eval $(klimax kubeconfig env dev)

# Or merge it into ~/.kube/config and switch to it
$ klimax kubeconfig use dev

Labeling clusters

Relabel the nodes of a cluster that's already running — no recreate needed. Repeatable -l key=value sets or overwrites a label (--overwrite is the default); -l key- removes one. It runs kubectl label nodes --all under the hood.

$ klimax cluster label dev -l tier=frontend -l disktype=ssd
$ klimax cluster label dev -l disktype-              # remove the label

Deleting clusters

Pass a name to delete one cluster, run it bare for an interactive multi-select picker, or match a set with -l / --selector (confirms unless -y).

$ klimax cluster delete staging
$ klimax cluster delete                    # interactive picker (Space toggles)
$ klimax cluster delete -l env=test --yes   # delete all matching, no prompt

End-to-end smoke test

Runs against your current kubectl context. --cleanup removes the test workload instead of deploying it.

$ klimax cluster e2e-test-nginx
$ klimax cluster e2e-test-nginx --cleanup   # delete the nginx pod and service

Kubeconfig

Every cluster keeps an isolated kubeconfig. The klimax kubeconfig family (alias klimax kc) prints its path, exports it, or merges it into your default ~/.kube/config.

Command	Description
`klimax kubeconfig path <name>`	Print the path to the cluster's kubeconfig file.
`klimax kubeconfig env <name>`	Print `export KUBECONFIG=<path>` — `eval` it to use the cluster's isolated kubeconfig in the current shell.
`klimax kubeconfig merge <name>`	Merge the cluster's context into `~/.kube/config`.
`klimax kubeconfig use <name>`	Merge and switch the active kubectl context to it.
`klimax kubeconfig remove <name>`	Remove the cluster's context, cluster, and user from `~/.kube/config` (alias `rm`).

$ eval $(klimax kubeconfig env dev)   # use dev's isolated kubeconfig here
$ klimax kubeconfig use dev           # merge + switch active context
$ klimax kubeconfig path dev
$ klimax kubeconfig remove dev        # clean it out of ~/.kube/config

♻

klimax cluster use and cluster merge still work as deprecated aliases — cluster use maps to kubeconfig env, cluster merge to kubeconfig merge. Prefer the kubeconfig forms.

Fleets

The top-level klimax fleet command operates on live clusters grouped by the klimax.dev/fleet=<name> node label (membership is derived from running clusters, not the manifest). See Fleet management and the Fleet resource.

Command	Description
`klimax fleet list`	Group clusters by `klimax.dev/fleet` (`-o text`/`json`/`yaml`).
`klimax fleet describe <name>`	Show a fleet's members with their num, ports, nodes, and labels (aliases `desc`, `show`).
`klimax fleet create -f <file>`	Create a manifest's clusters — delegates to `cluster apply -f` (`--dry-run`, `--max-parallel`).
`klimax fleet delete <name>`	Delete a fleet's clusters, resolved by label (`-y` to skip the prompt).
`klimax fleet delete -f <file>`	Delete a manifest's clusters — same as `cluster delete -f`.
`klimax fleet label <name> -l <k=v>`	Apply node labels to every cluster in the fleet (`-l key-` removes).

$ klimax fleet list
$ klimax fleet describe dev-fleet
$ klimax fleet create -f fleet.yaml --dry-run
$ klimax fleet label dev-fleet -l tier=frontend
$ klimax fleet delete dev-fleet -y

Registry

Command	Description
`klimax registry clean-cache`	Remove all registry mirror cache data and their containers.

$ klimax registry clean-cache
$ klimax up                       # restart the mirrors afterwards

❄

With the default cacheStorage: "host", mirror blobs live at ~/.klimax/registry-cache/ and survive klimax destroy. clean-cache is how you wipe them on purpose. See Registry mirrors.

Skill

Install the klimax Agent Skill so AI coding tools like Claude Code know how to drive klimax.

Command	Description
`klimax skill install`	Install the bundled `SKILL.md` into an AI tool's skills directory (Claude Code by default).
`klimax skill path`	Print where the skill is installed for Claude Code.

Flag (on `install`)	Description
`--claude`	Install into `~/.claude/skills/klimax/` (default `true`).
`--print`	Write the skill to `stdout` instead of installing.
`-f`, `--force`	Overwrite an already-installed skill.

$ klimax skill install            # → ~/.claude/skills/klimax/SKILL.md
$ klimax skill install --print     # emit to stdout for other tools
$ klimax skill path

Completion

Generate a shell auto-completion script for bash, zsh, fish, or powershell.

# zsh — add to ~/.zshrc to persist
$ source <(klimax completion zsh)

# bash
$ source <(klimax completion bash)

# fish
$ klimax completion fish > ~/.config/fish/completions/klimax.fish

Introduction

Install, upgrade, wipe

Cluster management

Configuration

Reference

Ecosystem

CLI reference

Global usage

Logging

VM lifecycle

Docker access

Clusters

`cluster create` flags

Fleets — `apply` & `delete -f`

Listing, switching, merging

Labeling clusters

Deleting clusters

End-to-end smoke test

Kubeconfig

Fleets

Registry

Skill

Completion

See also

Introduction

Install, upgrade, wipe

Cluster management

Configuration

Reference

Ecosystem

CLI reference

Global usage

Logging

VM lifecycle

Docker access

Clusters

cluster create flags

Fleets — apply & delete -f

Listing, switching, merging

Labeling clusters

Deleting clusters

End-to-end smoke test

Kubeconfig

Fleets

Registry

Skill

Completion

See also

`cluster create` flags

Fleets — `apply` & `delete -f`