mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
5306963cce
- docs/getting-started.md — install per distro, first use, common workflows - docs/architecture.md — 9-crate dependency graph, design decisions, data flow - docs/manifest-spec.md — manifest v1 specification - docs/lock-spec.md — lock file v2 specification - docs/store-spec.md — store format v2 specification - docs/hash-contract.md — two-phase identity hashing algorithm - docs/security-model.md — threat model, mount/device/env policy, privilege model - docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees - docs/protocol-v1.md — remote protocol v1 draft - docs/layer-limitations-v1.md — phase 1 layer limitations - docs/api-reference.md — public API reference (Engine, D-Bus) - docs/versioning-policy.md — semantic versioning, deprecation policy - docs/verification.md — release artifact verification (SHA256, cosign, SBOM) - docs/e2e-testing.md — E2E test guide with distro-specific prerequisites - README.md — project overview, features, quick start, installation - CONTRIBUTING.md — development setup, architecture principles, code standards - CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
# Karapace CLI Stability Contract
|
|
|
|
## Scope
|
|
|
|
This document defines the stability guarantee for the Karapace CLI between 1.x releases.
|
|
|
|
## Stable Commands (21)
|
|
|
|
The following commands have **stable signatures** — no breaking changes to arguments, flags, or output format between 1.x releases:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `build` | Build environment from manifest |
|
|
| `rebuild` | Destroy + rebuild environment |
|
|
| `enter` | Enter environment interactively |
|
|
| `exec` | Execute command inside environment |
|
|
| `destroy` | Destroy environment |
|
|
| `stop` | Stop a running environment |
|
|
| `freeze` | Freeze environment (read-only overlay) |
|
|
| `archive` | Archive environment (preserve, prevent entry) |
|
|
| `list` | List all environments |
|
|
| `inspect` | Show environment metadata |
|
|
| `diff` | Show overlay drift |
|
|
| `snapshots` | List snapshots for an environment |
|
|
| `commit` | Commit overlay drift as snapshot |
|
|
| `restore` | Restore overlay from snapshot |
|
|
| `gc` | Garbage collect orphaned store data |
|
|
| `verify-store` | Check store integrity |
|
|
| `push` | Push environment to remote store |
|
|
| `pull` | Pull environment from remote store |
|
|
| `rename` | Rename environment |
|
|
| `doctor` | Run diagnostic checks on system and store |
|
|
| `migrate` | Check store version and show migration guidance |
|
|
|
|
## Zero-Maintenance Commands (2)
|
|
|
|
These commands are auto-generated and have no hand-maintained logic:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `completions` | Generate shell completions (bash/zsh/fish/elvish/powershell) |
|
|
| `man-pages` | Generate man pages |
|
|
|
|
**Total: 23 commands.**
|
|
|
|
## Global Flags
|
|
|
|
All commands accept these flags (stable):
|
|
|
|
- `--store <path>` — custom store location (default: `~/.local/share/karapace`)
|
|
- `--json` — structured JSON output on all query and store commands
|
|
- `--verbose` / `-v` — enable debug logging
|
|
- `--trace` — enable trace-level logging (more detailed than `--verbose`)
|
|
|
|
## What "Stable" Means
|
|
|
|
- **No removed flags** — existing flags continue to work.
|
|
- **No changed flag semantics** — same flag produces same behavior.
|
|
- **No changed exit codes** — exit code meanings are fixed.
|
|
- **No changed JSON output keys** — new keys may be added, existing keys are never removed or renamed.
|
|
- **New flags may be added** — additive changes are allowed.
|
|
|
|
## What May Change
|
|
|
|
- Human-readable (non-JSON) output formatting.
|
|
- Spinner and progress indicator appearance.
|
|
- Error message wording (not error codes).
|
|
- Addition of new commands.
|
|
- Addition of new optional flags to existing commands.
|
|
|
|
## Removed Commands
|
|
|
|
The following commands were removed before 1.0 and will not return:
|
|
|
|
`init`, `preset`, `list-presets`, `export-app`, `unexport-app`, `quick`, `validate`, `verify-lock`, `export`, `list-images`, `remove-image`, `remote-list`, `tui`
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | Success |
|
|
| 1 | General failure |
|
|
| 2 | Manifest error (parse, validation) |
|
|
| 3 | Store error (integrity, version mismatch) |
|