lib

kix lib manages the Kix library locked in your project’s flake.lock. Its update subcommand moves your locked Kix library revision to match the version of Kix you are running.

Note

This page is hand-maintained from cli/kix-cli/src/cli.rs, cli/kix-cli/src/commands/library.rs, and cli/kix-core/src/library.rs. When flag definitions or behavior change in the Rust source, update this page in the same change.

Synopsis

kix lib update [--dry-run] [--flake <FLAKE>]

Why the Kix library and Kix versions stay aligned

When a cluster uses Helm charts (kix.helmChart, scope.helm.importChart, or scope.helm.importChartCrds), both the Kix library and Kix record the exact Helm 3 and Helm 4 versions used to render templates (kix/lib/helm-versions.json in the Kix library, and cli/kix-core/runtime/programs.json in Kix). Keeping those versions identical guarantees that helm template produces the same resource hashes on every machine.

If you upgrade Kix (or update flake.lock) and the two sides disagree on a Helm version, Kix stops before rendering the chart and prints a mismatch error telling you how to align them:

• If your installed Kix is newer than the Kix library revision in flake.lock, run kix lib update to move flake.lock to v<kix-version>.
• If your flake.lock is already ahead of your installed Kix, upgrade Kix to match the version reported in the error.

Flags (kix lib update)

Flag	Default	Description
--dry-run	false	Resolve github:kix-run/kix/v<version> and print the lockfile change that would occur without writing flake.lock.
--flake <FLAKE>	.	Path to the flake directory containing flake.nix and flake.lock (also read from KIX_FLAKE).

Global flags -v / --verbose, -q / --quiet, and --no-color also apply. -o / --output is ignored.

How kix lib update updates flake.lock

kix lib update reads flake.lock and finds the input locked to github:kix-run/kix (or named kixpkgs or kix). If an input uses follows, Kix updates the declaring input. It then locks that input to github:kix-run/kix/v<version>.

It modifies only flake.lock and never edits flake.nix.

For this lockfile update to work cleanly, your flake.nix should declare kixpkgs as an unpinned GitHub input:

{
  inputs.kixpkgs.url = "github:kix-run/kix";
}

When kix lib update asks you to edit flake.nix instead

kix lib update refuses to overwrite inputs that are pinned or non-standard in flake.nix, and prints instructions instead:

• Pinned tag, branch, or commit in flake.nix (for example, github:kix-run/kix/v0.6.0): kix lib update will not silently override a ref written in flake.nix. Change the input URL in flake.nix to github:kix-run/kix/v<version> (or remove the /v... ref from flake.nix so kix lib update can manage the version in flake.lock) and run kix lib update again.
• Custom fork or Git URL: Point the input in flake.nix at github:kix-run/kix/v<version>, or move that copy of Kix to the v<version> release.
• The former address github:kix-run/kixpkgs: the Kix library moved to github:kix-run/kix, and the old repository gets no new releases. Point the input in flake.nix at github:kix-run/kix, then run kix lib update again.
• Local path: input: Point the input in flake.nix at github:kix-run/kix/v<version>, or check out the v<version> release in that local directory.

Examples

Preview the lockfile change without writing flake.lock:

❱ kix lib update --dry-run

Kix library: 0.6.0 -> 0.7.0. This was a dry run, so flake.lock is unchanged.

Update flake.lock in the current directory:

❱ kix lib update

Kix library: 0.6.0 -> 0.7.0. Commit flake.lock to share this with your team.

When flake.lock already matches the installed Kix:

Kix library is already 0.7.0.

Exit status

• 0 when flake.lock is updated (or already at the target revision, or --dry-run succeeds).
• 1 when the flake has no kixpkgs input, when flake.nix pins a ref, fork, or path: input that kix lib update cannot update on its own, or when Kix cannot fetch the target release tag.