# Installation


kli installs on Linux and macOS. The canonical route is a prebuilt binary fetched by the install script; Nix and a from-source build are also supported.

## Install command

```sh
curl -fsSL https://kli.kleisli.io | sh
```

The script is served at the site root. There is no `/install` route.

The script detects the platform, downloads the matching release tarball, verifies the checksum when one is published, extracts the payload, and writes a `kli` wrapper. When the install directory's `bin` is not on `PATH`, it prints the `export PATH=…` line to add.

## Installer environment variables

Set these in the environment of the `curl … | sh` invocation.

| Variable | Default | Effect |
|---|---|---|
| `KLI_VERSION` | latest published release | Pin a version tag, e.g. `v0.1.0`. When unset, the script resolves the latest tag from the GitHub releases API. |
| `KLI_INSTALL_DIR` | `~/.local`; `/usr/local` when run as root | Install root. The payload goes under `<root>/lib/kli` and the wrapper at `<root>/bin/kli`. |
| `KLI_DOWNLOAD_BASE` | the GitHub release for the resolved version | Override the download origin wholesale: a private mirror, an air-gapped copy, or a local server. When set, version resolution is skipped and the artifact and `checksums.txt` are fetched from this base. |

A pinned-version invocation:

```sh
KLI_VERSION=v0.1.0 curl -fsSL https://kli.kleisli.io | sh
```

## On-disk layout

The installer lays out the payload under `<root>/lib/kli` and puts a small wrapper on `PATH`.

| Path | Contents |
|---|---|
| `<root>/lib/kli/bin/kli` | The relocatable image launcher. It self-locates from its own directory, sets the data directory and dynamic-library search path, and execs the image. |
| `<root>/lib/kli/lib/` | Bundled runtime libraries (dynamic loader and shared objects) the image loads. |
| `<root>/lib/kli/share/kli/` | Runtime resource roots (built-in skills, TUI themes). |
| `<root>/bin/kli` | The wrapper on `PATH`. It execs `<root>/lib/kli/bin/kli` by absolute path. |

The wrapper invokes the launcher by absolute path, not a symlink: the launcher roots its lookups off its own directory, so a symlinked entry would mis-root.

Checksum verification is best-effort. The script fetches `checksums.txt` from the same base and compares against `sha256sum` or `shasum`. A mismatch aborts the install. When neither tool is present and no checksum file is published, verification is skipped.

Re-running the script over an existing install removes the previous `bin`, `lib`, `share`, and `VERSION` under `<root>/lib/kli` before extracting, so an upgrade is clean.

## Supported targets

Prebuilt binaries are published for three targets:

| OS | Architecture | Prebuilt binary |
|---|---|---|
| Linux | x86_64 | yes |
| Linux | aarch64 (arm64) | yes |
| macOS | aarch64 (Apple Silicon) | yes |
| macOS | x86_64 (Intel) | no |

Intel macOS has no prebuilt binary. Install via Nix or from source.

## Nix

The flake at `github:kleisli-io/kli` builds for `x86_64-linux`, `aarch64-linux`, and `aarch64-darwin`. Two entry points run or install the program:

```sh
nix run github:kleisli-io/kli
nix profile install github:kleisli-io/kli
```

| Output | Contents |
|---|---|
| `overlays.default` | Adds `kli` to a nixpkgs overlay; the package is then `pkgs.kli`. |
| `packages.<system>.kli` (and `.default`) | The `kli` program derivation. |

The overlay and package, wired into a NixOS or home configuration:

```nix
{
  inputs.kli.url = "github:kleisli-io/kli";

  # nixpkgs.overlays = [ inputs.kli.overlays.default ];
  # environment.systemPackages = [ pkgs.kli ];
}
```

That installs kli itself. To bake extensions and settings into the image, use [the `programs.kli` module](/kli/config/nix-module) instead.

## From source

A source build needs SBCL and [qlot](https://github.com/fukamachi/qlot). The external Common Lisp systems are pinned in `qlfile`.

```sh
qlot install
qlot exec sbcl --script build.lisp
./bin/kli
```

`qlot install` resolves the pinned systems. `build.lisp` loads the `kli` system and dumps a standalone image to `bin/kli` in the working directory.