CLI Reference

The complete kazma, kazma-tui, and kazma-web command surface, every flag, and working examples — all verified against kazma-cli/ source.

1. Entry points

Defined in pyproject.toml:73-76:

Command	Module	What it is
`kazma`	`kazma_cli.main:main`	The primary CLI (ask, acp, hub, gateway, swarm, project, docs, completion, update).
`kazma-tui`	`kazma_tui.app:main`	The Textual TUI dashboard.
`kazma-web`	`kazma_ui.app:main`	The FastAPI Web UI server (alias of `kazma serve`).

Framework note: The top-level kazma command is hand-rolled argv parsing (an if/elif chain over sys.argv[1:] in main.py:39-94) — not Click. Only the kazma hub subtree uses Click (kazma_core/hub/cli.py:104). Global early option --no-banner is stripped before dispatch (main.py:28-32).

2. `kazma` — top-level tree

kazma
├── (no args)              # banner + status + help hint
├── status                 # probe running server, print versions
├── serve [port]           # launch Web UI (uvicorn)
├── ask [options] <prompt> # in-process agent (no uvicorn)
├── acp                    # ACP JSON-RPC on stdio (Zed / JetBrains)
├── wizard                 # interactive skill-install wizard
├── hub ...                # skill hub (Click group)
├── docs <build|serve>     # build/serve the Docusaurus docs site
├── completion ...         # shell tab-completion
├── project ...            # .kazma/ project config
├── gateway ...            # gateway control via REST
├── swarm ...              # swarm orchestration via REST
├── update                 # check/install CLI updates
├── migrate ...            # export/verify/import an installation
└── --help | -h | help     # print command list

2.1 `kazma` (no args)

Prints the startup banner, runs config checks, prints status, and a help hint (main.py:35-37). Honors --no-banner.

2.2 `kazma status`

Probes /api/gateway/status and /api/swarm/status on the running server, prints Python/Kazma versions, config path, and key package versions (main.py:352-439).

kazma status

2.3 `kazma serve [port]`

Launches the Web UI via uvicorn kazma_ui.app:create_app --factory. Default port 8000. Binds 127.0.0.1 normally; switches to 0.0.0.0 only when KAZMA_SECRET is set (main.py:97-114, 110).

kazma serve            # 127.0.0.1:8000
kazma serve 9090       # 127.0.0.1:9090
KAZMA_SECRET=xxx kazma serve   # 0.0.0.0:8000 (approval endpoints protected)

Security: Never run kazma serve on 0.0.0.0 without KAZMA_SECRET. The HITL approval endpoint would otherwise be unauthenticated.

2.4 `kazma wizard`

Runs the interactive skill-installation wizard (kazma_core.cli.wizard.SkillInstallationWizard, main.py:117-123).

2.5 `kazma docs`

Builds or serves the Docusaurus docs site under docs/ (main.py:133-202).

kazma docs build        # npm install && npm run build
kazma docs serve        # npm run start (default port 3000)
kazma docs serve 4000   # custom port

2.6 `kazma ask [options] <prompt>`

Runs the LangGraph supervisor in-process (kazma_core.cli.ask). Does not start uvicorn. Tokens stream to stdout; tool lines go to stderr.

Flag	Meaning
`--workspace, -w PATH`	Workspace root (default: cwd)
`--yolo`	Allow danger tools without HITL
`--plan`	Enter plan mode (read-only until the model plans)
`--json`	NDJSON events on stdout (`token` / `tool_*` / `hitl` / `done`)
`--no-stream`	Wait for the full reply (with `--json`, a single object)
`--thread ID`	Reuse a thread id
`--model NAME`	Switch model for this process
`--acp`	Agent Client Protocol stdio server (same as `kazma acp`)

On a TTY, danger tools prompt y/N (or a = allow for this session). Piped stdin / kazma ask - fail closed unless --yolo.

kazma ask "What files define the supervisor graph?"
kazma ask --plan "Add a rate limiter to the API"
kazma ask --json "fix the tests"
echo "summarize README.md" | kazma ask --json --no-stream -

2.7 `kazma acp`

Agent Client Protocol JSON-RPC on stdio (initialize, session/new, session/prompt, session/cancel). Streams session/update (agent_message_chunk, tool_call, tool_call_update) and asks the editor to approve danger tools via session/request_permission. Patch tools send ACP diff content (oldText / newText) so Zed can render a review stack. session/cancel aborts the in-flight turn.

kazma acp
kazma ask --acp --workspace /path/to/repo

Zed — ~/.config/zed/settings.json (Windows: %APPDATA%\Zed\settings.json):

{
  "agent_servers": {
    "Kazma": {
      "type": "custom",
      "command": "kazma",
      "args": ["acp"]
    }
  }
}

Open the Agent Panel, pick Kazma, start a thread. Danger tools prompt in the editor (Allow once / Allow for this session / Reject).

3. `kazma completion`

Shell tab-completion generation and install (main.py:224-286, completions.py).

Subcommand	Description
`kazma completion bash`	Print bash completion script.
`kazma completion zsh`	Print zsh completion script.
`kazma completion powershell` (aliases `pwsh`, `ps`)	Print PowerShell `Register-ArgumentCompleter` script.
`kazma completion install [shell]`	Auto-detect shell (PowerShell on win32; zsh/bash on POSIX) and install.
`--list-models`	Print available model names.
`--list-providers`	Print provider names.

Global flags (for completion data): --model, --provider, --yolo, --verbose, --no-banner, --help, -h.

4. `kazma project`

.kazma/ per-project config (main.py:289-328, project.py).

Subcommand	Args	Description
`kazma project init [path]`	default `.`	Create `.kazma/` with `rules.yaml`, `context.md`, `personality.yaml`, `tools.yaml`, `history/`. Idempotent.
`kazma project show [path]`	default `.`	Display parsed project config.
`kazma project validate [path]`	default `.`	Verify required files exist, YAML parses, `rules.yaml` has `language` and `git_branch`.

5. `kazma gateway`

Omnichannel gateway control via REST. All subcommands accept --port N and talk to http://localhost:\{port\} (gateway.py).

5.0 The `--port` flag (swarm / gateway)

Swarm and gateway commands target the server at http://localhost:8000 by default. The port resolves with this precedence:

Source	Priority
`--port N` (per command)	highest
`KAZMA_PORT` env var	middle
`8000` (default)	lowest

If the server is unreachable, the CLI prints Server not running. Start with: kazma serve and exits 1 (see exit codes).

Subcommand	Endpoint	Description
`kazma gateway status`	`GET /api/gateway/status`	Adapter table.
`kazma gateway start`	`POST /api/gateway/start`	Start gateway.
`kazma gateway stop`	`POST /api/gateway/stop`	Stop gateway.
`kazma gateway restart`	stop + 0.5 s + start	Restart gateway.
`kazma gateway refresh`	`POST /api/gateway/refresh-adapters`	Re-scan adapters.

kazma gateway status
kazma gateway restart --port 9090

6. `kazma swarm`

Swarm orchestration via REST (swarm.py). Value flags: --model, --provider, --type, --role, --context, --workers, --aggregation, --page, --page-size, --status, --port, --worker. Bool: --reset.

6.1 Status & workers

Subcommand	Description
`kazma swarm status`	`GET /api/swarm/status`.
`kazma swarm workers`	List workers.
`kazma swarm worker add <name> [--model --provider --type --role]`	`POST /api/swarm/workers`.
`kazma swarm worker spawn <name> <role> [--model --provider --type]`	`POST /api/swarm/workers/spawn`.
`kazma swarm worker remove <name>`	`DELETE /api/swarm/workers/\{name\}`.

6.2 Dispatch patterns

Subcommand	`type`	Description
`kazma swarm dispatch <worker> <prompt> [--context C]`	`dispatch`	Single worker.
`kazma swarm broadcast <prompt> [--context C]`	`broadcast`	All workers.
`kazma swarm consult <prompt> --workers a,b [--context C]`	`consult`	Parallel opinions + synthesis.
`kazma swarm pipeline --workers a,b,c <prompt>`	`pipeline`	Ordered stages + shared blackboard.
`kazma swarm fanout --workers a,b <prompt> [--aggregation strategy]`	`fan_out`	Parallel + aggregate.

# Dispatch one task to the "researcher" worker
kazma swarm dispatch researcher "Summarize today's oil prices"

# Fan out to three workers and vote on the result
kazma swarm fanout --workers a,b,c --aggregation vote "Best API design?"

# Run the standard pipeline
kazma swarm pipeline --workers researcher,refiner,builder,validator "Build a CLI tool"

6.3 Tasks, metrics, reliability

Subcommand	Description
`kazma swarm history [--type --status --page --page-size]`	`GET /api/swarm/tasks` (paginated).
`kazma swarm task <id>`	`GET /api/swarm/tasks/\{id\}`.
`kazma swarm metrics [--worker W]`	`GET /api/swarm/workers/\{W\}/metrics` (or `/metrics/all`).
`kazma swarm start` / `kazma swarm stop`	`POST /api/swarm/start` / `/stop`.
`kazma swarm approve <task_id>`	`POST /api/swarm/tasks/\{id\}/approve` (HITL checkpoint).
`kazma swarm reject <task_id>`	`POST /api/swarm/tasks/\{id\}/reject`.
`kazma swarm circuit-breaker [worker] [--reset]`	`GET /api/swarm/circuit-breakers`, per-worker, or `POST .../reset`.

7. `kazma update`

Primary operator upgrade path (kazma_cli/update.py). Prefer this over a manual git pull on production/git installs. Full guide: Kazma Update.

Flag	Purpose
`--check` / `-c`	Dry-run: show available update
`--force` / `-f`	Force sync even if already latest
`--yes` / `-y`	Skip confirmation
`--reinstall` / `-r`	Packages/extras only (repair wiped venv)
`--sync-main`	Checkout `main` first (feature-branch safety)
`--accept-discard-local-commits`	Allow hard-reset when local commits are ahead of `origin/main`

Auto-detects install type:

pip install → PyPI upgrade path.
git / monorepo → preflight (main-only) → named stash → hard-reset origin/main → restore stash → reinstall extras → postflight (HEAD + kazma_cli import). Never hard-resets a feature branch in place.

kazma update --check     # dry-run
kazma update --yes       # apply without prompting
kazma update --reinstall -y   # repair packages after a broken reinstall

8. `kazma migrate` — cross-machine migration

Move a full Kazma installation (config, secrets, memory, chat history, snapshots, assets) across machines/OSes without silent breakage. See Migration for the full guide and the three load-bearing invariants (vault pairing, path translation, atomic import).

kazma migrate export [--out PATH] [--no-assets]   # create a portable bundle
kazma migrate verify BUNDLE [--no-hash]           # check integrity without importing
kazma migrate import BUNDLE [--workspace PATH] [--reset-vault-key] [--dry-run]

Subcommand	Purpose
`export`	Bundle the current install into a `.zip` (SQLite files + Postgres dump + vault + assets)
`verify`	Validate bundle structure, sha256 hashes, manifest, vault-key fingerprint
`import`	Restore into this machine: staging → path-rewrite → backup → atomic swap

Postgres sources: set KAZMA_DB_CONTAINER so pg_dump is discovered via docker exec. See Migration → Postgres.

Vault-key mismatch: if the bundle’s vault key differs from the target’s, import aborts. Pass --reset-vault-key to overwrite (the existing target vault.db is backed up first).

9. `kazma hub` — skill hub (Click group)

The only Click-based subtree (kazma_core/hub/cli.py:104). Group options: --registry-path (env KAZMA_HUB_DB, default ~/.kazma/hub/registry.db), --hub-url (env KAZMA_HUB_URL, default https://hub.kazma.ai).

Subcommand	Description
`kazma hub register <path>`	Register a local skill.
`kazma hub search [query] [--capabilities --tags --author]`	Search the registry.
`kazma hub install <skill_id>`	Install a skill.
`kazma hub list`	List installed skills.
`kazma hub info <skill_id>`	Show skill details.
`kazma hub validate <path> [--json]`	Validate a skill manifest.
`kazma hub uninstall <skill_id>`	Remove a skill.
`kazma hub submit <path> [--json --source-url]`	POST to `\{hub_url\}/api/v1/skills/submit`.
`kazma hub status <submission_id> [--json]`	Submission status.
`kazma hub badge <skill_ref> [--json]`	Show certification badge.
`kazma hub certified [--json]`	List certified skills.
`kazma hub stats [--json]`	Registry stats.
`kazma hub check-certification <path> [--json]`	Check a skill against certification criteria.
`kazma hub sign <path> [--secret]`	HMAC-SHA256 sign the entry-point `.py` into the manifest. Requires `KAZMA_SECRET`. See Skills, MCP & Tools.

# Sign a skill (writes checksum + signature into skill_manifest.yaml)
KAZMA_SECRET=... kazma hub sign ./my-skill

# Search and install
kazma hub search "oil pricing" --capabilities mcp
kazma hub install oil-pricing-pro@1.2.0

10. `kazma-tui`

Launches the Textual TUI (kazma_tui.app:main → KazmaTUI().run()). Tabs: Dashboard, Chat, Files, Traces, Swarm, Settings. Initializes ModelRegistry/SwarmEngine singletons if launched standalone. Includes a HITL approval modal (widgets/hitl_modal.py).

kazma-tui
# or: python -m kazma_tui

11. `kazma-web`

Alias for launching the FastAPI Web UI server directly (kazma_ui.app:main). Defaults 127.0.0.1:8000; warns if binding 0.0.0.0 without KAZMA_SECRET (app.py:900-906).

kazma-web

12. Slash commands (in-chat)

These are typed inside a connected chat (Telegram/Discord/Slack/Web). Defined in kazma-gateway/.../slash_commands.py.

Command	Description
`/help`	List commands by category.
`/reset`	Clear conversation (handled in `graph.py:196`).
`/status`	Gateway health overview.
`/model` or `/models`	Interactive model selector (Telegram inline keyboard).
`/memory`	Memory subsystem stats.
`/cost`	Token spend for the session.
`/replay list \| <iter> \| compare <a> <b> \| clear`	Time-travel: list snapshots, restore (rewind), compare diff, clear.
`/fork <iter>`	Branch from a snapshot into a new thread (original stays intact).
`/config show \| model <n> \| personality <n> \| memory on\|off \| tools list \| tools toggle <n> \| export`	Config wizard.
`/personality`	Delegate to `/config personality`.
`/context`	Context-window token usage.
`/undo`	Stub — not implemented.
`/edit`	Stub — not implemented.
`hitl approve	deny <thread_id>`
`/swarm`	Swarm orchestration (Telegram-registered; interactive handler).

Parity note: /help text omits /hitl and /swarm even though both are functional. Telegram’s setMyCommands registers /swarm but not /hitl. Discord reserves /-prefixed commands for itself, so Kazma receives them as plain text. See Gateways & Platforms.

13. Exit codes {#exit-codes}

Code	Meaning
`0`	Success.
`1`	General failure / server unreachable (swarm & gateway commands print `Server not running. Start with: kazma serve` and exit `1` when the WebUI server is not running — start it first with `kazma serve`).
`2`	Argument/usage error (Click, `kazma hub` subtree only).

Swarm and gateway commands are REST clients: they exit non-zero whenever the WebUI server is not running. Always start the server (kazma serve) before invoking them.

Documentation Audit Notes

--help text prints “Kazma CLI v0.2.0” (main.py:75) while pyproject.toml is 0.3.0. Known drift.
kazma hub is the only Click subtree. All other commands are hand-rolled argv parsing — flag ordering and --help behavior may be less uniform than a pure-Click CLI.
/undo and /edit are stubs (slash_commands.py:257, 267) — present in the menu but explicitly “not yet implemented.”

CLI Reference

1. Entry points

2. kazma — top-level tree

2.1 kazma (no args)

2.2 kazma status

2.3 kazma serve [port]

2.4 kazma wizard

2.5 kazma docs

2.6 kazma ask [options] <prompt>

2.7 kazma acp

3. kazma completion

4. kazma project

5. kazma gateway

5.0 The --port flag (swarm / gateway)

6. kazma swarm