marcoallegretti/karapace
1
0
Fork 0
mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: document pin and build flags

Browse source 
Update CLI reference for:

- build/rebuild: --locked, --offline, --require-pinned-image
- pin: --check and --write-lock
This commit is contained in:
Marco Allegretti 2026-02-23 18:31:25 +01:00
parent d2bbe9b648
commit 52b42532ce
1 changed files with 19 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
docs/cli-reference.md
View file

@ -58,13 +58,16 @@ If `--template` is not provided, the command uses interactive prompts (requires
Build an environment from a manifest.
```
karapace build [manifest] [--name <name>]
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).
@ -73,11 +76,25 @@ Executes: parse → normalize → resolve → lock → build. Writes `karapace.l
Destroy the existing environment and build a new one from the manifest.
```
karapace rebuild [manifest] [--name <name>]
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.