karapace/docs/cli-reference.md

# CLI Reference

Binary: `karapace`. Defined in `crates/karapace-cli/src/main.rs`.

## Global flags

| Flag | Default | Description |
|------|---------|-------------|
| `--store <path>` | `~/.local/share/karapace` | Store directory path |
| `--json` | `false` | JSON output |
| `--verbose` / `-v` | `false` | Debug-level logging |
| `--trace` | `false` | Trace-level logging (implies debug) |

## Environment variables

| Variable | Used by | Description |
|----------|---------|-------------|
| `KARAPACE_LOG` | cli, dbus | Log level filter: `error`, `warn`, `info`, `debug`, `trace`. Overrides `--verbose`/`--trace`. |
| `KARAPACE_STORE` | dbus | Override default store path. |
| `KARAPACE_SKIP_PREREQS` | cli | Set to `1` to skip runtime prerequisite checks. |

## Exit codes

| Code | Constant | Condition |
|------|----------|-----------|
| 0 | `EXIT_SUCCESS` | Success |
| 1 | `EXIT_FAILURE` | General error |
| 2 | `EXIT_MANIFEST_ERROR` | Manifest parse or validation error |
| 3 | `EXIT_STORE_ERROR` | Store integrity or lock error |

Defined in `crates/karapace-cli/src/commands/mod.rs`.

---

## Commands

### `new`

Generate a new `karapace.toml` manifest in the current directory.

```
karapace new <name> [--template <template>] [--force]
```

| Argument | Description |
|----------|-------------|
| `name` | Human-readable name used in interactive prompts and output |

| Flag | Description |
|------|-------------|
| `--template` | One of: `minimal`, `dev`, `gui-dev`, `rust-dev`, `ubuntu-dev` |
| `--force` | Overwrite `./karapace.toml` if it already exists |

If `--template` is not provided, the command uses interactive prompts (requires a TTY). If `./karapace.toml` exists and `--force` is not set, the command prompts on a TTY; otherwise it fails.

### `build`

Build an environment from a manifest.

```
karapace build [manifest] [--name <name>] [--locked] [--offline] [--require-pinned-image]
```

| Argument | Default | Description |
|----------|---------|-------------|
| `manifest` | `karapace.toml` | Path to manifest file |
| `--name` | — | Assign a human-readable name |
| `--locked` | — | Require existing `karapace.lock` and fail on drift |
| `--offline` | — | Forbid network (host downloads and container networking) |
| `--require-pinned-image` | — | Fail if `base.image` is not an http(s) URL |

Executes: parse → normalize → resolve → lock → build. Writes `karapace.lock` next to the manifest. Requires runtime prerequisites (user namespaces, fuse-overlayfs).

### `rebuild`

Destroy the existing environment and build a new one from the manifest.

```
karapace rebuild [manifest] [--name <name>] [--locked] [--offline] [--require-pinned-image]
```

Same arguments as `build`. The old environment is destroyed only after the new one builds successfully.

### `pin`

Rewrite a manifest to use an explicit pinned base image reference.

```
karapace pin [manifest] [--check] [--write-lock]
```

| Argument | Default | Description |
|----------|---------|-------------|
| `manifest` | `karapace.toml` | Path to manifest file |
| `--check` | — | Exit non-zero if `base.image` is not already pinned |
| `--write-lock` | — | After pinning, run a build to write/update `karapace.lock` |

### `enter`

Enter an environment interactively, or run a command.

```
karapace enter <env_id> [-- cmd...]
```

| Argument | Description |
|----------|-------------|
| `env_id` | Full env_id, short_id, or name |
| `-- cmd...` | Optional command to run instead of interactive shell |

Sets state to `Running` on entry, back to `Built` on exit.

### `exec`

Run a command inside an environment (non-interactive).

```
karapace exec <env_id> -- <cmd...>
```

| Argument | Description |
|----------|-------------|
| `env_id` | Full env_id, short_id, or name |
| `cmd...` | Required. Command and arguments. |

### `destroy`

Destroy an environment and its overlay.

```
karapace destroy <env_id>
```

Cannot destroy a `Running` environment. Stop it first.

### `stop`

Stop a running environment.

```
karapace stop <env_id>
```

Sends `SIGTERM`. If the process does not exit within the timeout, sends `SIGKILL`.

### `freeze`

Freeze an environment. Prevents further writes.

```
karapace freeze <env_id>
```

### `archive`

Archive an environment. Prevents entry but preserves store data.

```
karapace archive <env_id>
```

Archived environments are protected from garbage collection.

### `list`

List all environments.

```
karapace list
```

Output columns: `SHORT_ID`, `NAME`, `STATE`, `ENV_ID`.

### `inspect`

Show environment metadata.

```
karapace inspect <env_id>
```

### `diff`

Show changes in the writable overlay.

```
karapace diff <env_id>
```

Lists added, modified, and removed files relative to the base layer.

### `snapshots`

List snapshots for an environment.

```
karapace snapshots <env_id>
```

### `commit`

Save overlay changes as a snapshot layer.

```
karapace commit <env_id>
```

Only valid for `Built` or `Frozen` environments.

### `restore`

Restore an environment's overlay from a snapshot.

```
karapace restore <env_id> <snapshot_hash>
```

| Argument | Description |
|----------|-------------|
| `env_id` | Environment to restore |
| `snapshot_hash` | Layer hash from `snapshots` output |

### `gc`

Garbage collect orphaned store data.

```
karapace gc [--dry-run]
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Report what would be removed without deleting |

### `verify-store`

Verify integrity of all objects in the store.

```
karapace verify-store
```

Re-hashes every object, layer, and metadata entry against its stored key or checksum.

### `push`

Push an environment to a remote store.

```
karapace push <env_id> [--tag <name@tag>] [--remote <url>]
```

| Flag | Description |
|------|-------------|
| `--tag` | Registry key, e.g. `my-env@latest` |
| `--remote` | Remote URL. Overrides `~/.config/karapace/remote.json`. |

Skips blobs that already exist on the remote.

### `pull`

Pull an environment from a remote store.

```
karapace pull <reference> [--remote <url>]
```

| Argument | Description |
|----------|-------------|
| `reference` | Registry key (`name@tag`) or raw `env_id` |

Downloaded objects are verified with blake3 before storage.

### `rename`

Rename an environment.

```
karapace rename <env_id> <new_name>
```

Names must match `[a-zA-Z0-9_-]`, 1–64 characters. Validated in `karapace-store/src/metadata.rs::validate_env_name`.

### `completions`

Generate shell completions.

```
karapace completions <shell>
```

Supported shells: `bash`, `zsh`, `fish`, `elvish`, `powershell`.

### `man-pages`

Generate man pages.

```
karapace man-pages [dir]
```

| Argument | Default | Description |
|----------|---------|-------------|
| `dir` | `man` | Output directory |

### `doctor`

Check system prerequisites and store health.

```
karapace doctor
```

Checks: user namespace support, `fuse-overlayfs` availability, `curl` availability. Exits non-zero if any check fails.

### `migrate`

Check store format version and show migration guidance.

```
karapace migrate
```

### `tui`

Start the terminal UI.

```
karapace tui
```

This command is interactive and rejects `--json`.