Reference CLI

Global flags

These flags are accepted by every kix command and may appear before or after the subcommand. A command that has no use for a flag ignores it, and its --help does not list it. kix --help lists them all. Each flag except --no-color can also be set with the environment variable in the table; the flag wins over the variable.

This page is hand-maintained. Check GlobalArgs and SCOPED_GLOBALS in cli/kix-cli/src/cli.rs, cli/kix-cli/src/main.rs, and cli/kix-cli/src/output.rs when in doubt, and cli/kix-cli/src/plugin.rs for plugins.

Flags

Flag	Variable	Default	Meaning
`-o`, `--output <FORMAT>`	`KIX_OUTPUT`	Varies by command	`text`, `json`, `yaml`, or `markdown`. See Output formats for which commands honour which values.
`-v`, `--verbose`	`KIX_VERBOSE`, a count	Off	Log more to stderr. Repeat for more: `-v` logs Kix at info level, `-vv` at debug, `-vvv` everything at debug. Without it, warnings are logged, except those the Kubernetes client writes for an error response it then returns to Kix.
`-q`, `--quiet`	`KIX_QUIET`	Off	Suppress progress and informational output, and log errors only. Results still print.
`--no-color`	`NO_COLOR`, below	Off	Disable coloured result output. Deploy and gc progress lines currently still use terminal clear-line control sequences.
`--context <CONTEXT>`	`KIX_CONTEXT`	Current kubeconfig context	Kubeconfig context for every command that talks to a cluster. `logs` and `pf` pass it to `kubectl`.
`--flake <FLAKE>`	`KIX_FLAKE`	`.`	Flake to evaluate clusters from. A value without `:` is a local path, resolved against the working directory; anything else, such as `github:org/repo`, is passed as a remote flake reference. Commands that use the eval cache currently fail on a remote reference.
`--no-cache`	`KIX_NO_CACHE`	Off	Skip the Kix eval cache and re-evaluate the cluster every time. See Eval cache behavior.
`--override-input <INPUT> <URL>`	`KIX_OVERRIDE_INPUT`, names and URLs separated by spaces, read only without the flag	None	Override a flake input’s URL during evaluation. Repeatable, two values each time. Kix skips the eval cache when this is set.
`-h`, `--help`			Print help. `-h` prints a summary, `--help` the long form.
`-V`, `--version`			Print the version.

Which commands read which flag

-v, -q, and --no-color apply to every command. The other flags apply only where the table shows them; elsewhere they are accepted and have no effect.

Command	`-o`	`--context`	`--flake`	`--no-cache`	`--override-input`
`build`, `check`, `graph`, `inspect`, `images`, `list`	yes		yes	yes	yes
`status`	yes	yes	yes	flat view only	yes
`diff`	yes	yes	yes		yes
`plan`	yes	yes	yes		yes
`deploy`, `gc`, `migrate domain`, `logs`, `pf`		yes	yes		yes
`export`			yes		yes
`rollback`	yes	yes	yes		yes
`drift`	yes	yes
`health`		yes	yes		yes
`snapshot save`		yes
`compliance sbom`	yes		yes		yes
`compliance attest`	yes	yes	yes		yes
`compliance audit`			yes	yes	yes
`pin`	yes		yes
`lib`, `doctor`, `upgrade`			yes
`completions`

--no-cache applies only to commands that read the eval cache. kix pin uses --flake only as a place to look for pins.json, and kix doctor uses it to locate kix.toml. rollback, health, and status --operator use --flake and --override-input only to evaluate the cluster name when no Activation record in the current context already carries <CLUSTER> as its kix.run/cluster label. -o on rollback applies only with --list, and on deploy only with --dry-run.

Environment variables

Variable	Effect
`NO_COLOR`	Any value disables colour, as `--no-color` does. Colour is also off when `TERM=dumb` or stdout is not a terminal. Deploy and gc have the progress-line exception noted above.
`KIX_LOG`	A tracing filter, such as `kix=debug` or `debug`, that replaces the level chosen by `-v` and `-q`.
`KIX_NO_INTERACTIVE`	Any value makes Kix treat the terminal as non-interactive, so commands that ask for confirmation refuse to prompt and need `--yes`. Stdin that is not a terminal has the same effect.
`KIX_RUNTIME_DIR`	Directory that holds the Kix runtime (`nix`, `helm`, `kubectl`, `sops`) and `manifest.json`. See `kix doctor`.
`KIX_STORE_ROOT`	Root directory for Kix’s local store under the default `kix` builder. Defaults to `$XDG_CACHE_HOME/kix/store` (or `~/.cache/kix/store` when `XDG_CACHE_HOME` is unset). Setting `KIX_STORE_ROOT` on a project that sets `builder = "nix"` in `kix.toml` is an error.

The variables that tune how Kix talks to the Kubernetes API are listed in API server retries and request limits. Registry credentials for kix pin are listed on kix pin.

A variable that turns a flag on or off is off when it is empty or one of false, f, no, n, off, or 0, in any case, and on for any other value.

Plugins

kix NAME ARGS..., where NAME is not a kix command, runs the program kix-NAME with ARGS. Kix looks for it in the absolute directories on PATH, the way git and cargo find their external commands. A plugin can be any executable; NAME may hold letters, digits, -, and _.

Global flags go before NAME. Kix passes them to the plugin as the variables in the table above, and --no-color as NO_COLOR=1. Everything after NAME goes to the plugin unchanged. KIX_FLAKE is passed as given, so a relative path such as ../infra is relative to the directory kix ran in. An --override-input value with a space can’t be passed, and Kix refuses it.
KIX_BIN is the path of the kix that ran the plugin. A plugin that runs $KIX_BIN gets the same version, and that kix reads the same variables, so it has the user’s flags without being given them. Pass a flag to override one.
Kix replaces itself with the plugin, so its exit status is the plugin’s.
A NAME with no plugin is an error, as before, with a suggestion when it is close to a command. kix help NAME does not reach a plugin; run kix NAME --help, if the plugin has one.

Examples

❱ kix --flake ../infra list clusters

❱ kix deploy demo --context kind-demo -v

❱ kix build demo --override-input kixpkgs git+file:///home/me/src/kixpkgs

❱ kix --context prod enterprise status