# `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

```text
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:

```nix
{
  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`:

<Command commands={["kix lib update --dry-run"]} />

```text
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:

<Command commands={["kix lib update"]} />

```text
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:

```text
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.