From 78f6d4e65e8d407b5f575d87246783f8a3db12d4 Mon Sep 17 00:00:00 2001
From: Marco Allegretti <marco@karapace.dev>
Date: Mon, 23 Feb 2026 12:16:12 +0100
Subject: [PATCH] Document new and tui commands

Update README and CLI reference to include 'karapace new' and 'karapace tui'.

Note that 'tui' rejects --json output.
---
 README.md             |  6 ++++--
 docs/cli-reference.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 17f1a1a..60f2fc5 100644
--- a/README.md
+++ b/README.md
@@ -64,9 +64,10 @@ See `examples/` for more manifests: `minimal.toml`, `dev.toml`, `gui-dev.toml`,
 
 ## Commands
 
-23 commands. All accept `--json`, `--store <path>`, `--verbose`, `--trace`.
+25 commands. All accept `--store <path>`, `--verbose`, `--trace`. All except `tui` accept `--json`.
 
 ```
+new <name> [--template] [--force] Generate `karapace.toml`
 build [manifest] [--name]       Build environment
 rebuild [manifest] [--name]     Destroy + rebuild
 enter <id> [-- cmd...]          Enter environment
@@ -90,6 +91,7 @@ doctor                          Check prerequisites
 migrate                         Check store version
 completions <shell>             Shell completions
 man-pages [dir]                 Generate man pages
+tui                             Terminal UI
 ```
 
 ## Workspace
@@ -101,7 +103,7 @@ karapace-schema     Manifest, normalization, lock file, identity
 karapace-store      Objects, layers, metadata, WAL, GC, integrity
 karapace-runtime    Backends (namespace/oci/mock), images, security
 karapace-core       Engine: lifecycle orchestration
-karapace-cli        CLI (23 commands)
+karapace-cli        CLI (25 commands)
 karapace-dbus       D-Bus service (optional)
 karapace-tui        Terminal UI (optional)
 karapace-remote     Remote store client, push/pull
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 7ac6630..247b421 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -34,6 +34,25 @@ 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.
@@ -284,3 +303,13 @@ Check store format version and show migration guidance.
 ```
 karapace migrate
 ```
+
+### `tui`
+
+Start the terminal UI.
+
+```
+karapace tui
+```
+
+This command is interactive and rejects `--json`.