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
├── doctor                 # which model and provider will be used, and will it work
├── acquisition status     # cached crawler errors, usage and credit evidence
├── serve [port]           # launch Web UI (uvicorn)
├── ask [options] <prompt> # in-process agent (no uvicorn)
├── acp                    # ACP JSON-RPC on stdio (Zed / JetBrains)
├── mcp                    # MCP server on stdio — the whole tool registry, behind the HITL gate
├── wizard                 # interactive skill-install wizard
├── hub ...                # skill hub (Click group)
├── agent-skills ...       # list, verify and sign installed Agent Skills
├── 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

`kazma acquisition status`

Read this installation’s retained crawl outcomes, request reservations, reported usage and cached credit freshness without contacting providers:

kazma acquisition status
kazma acquisition status --job <retained-job-id> --json
kazma acquisition status --language ar

Unknown charges and unsupported balances remain unavailable. Reservations are request upper bounds, not money spent. Live capacity refers to this CLI process; persisted job/accounting evidence belongs to the installation. The command exits with 1 on unavailable status or failed readiness and 0 when ready.

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 tool for this session / Reject). “For this session” allows that one tool for the thread (30 minutes by default, KAZMA_HITL_GRANT_TTL_SECONDS), as the web card’s “Allow tool” does; it never switches off approvals for the other tools. A tool that always asks (posting to X) offers Allow once and Reject only. In a terminal, kazma ask asks y/N/a, where a is the same per-tool allowance.

2.8 `kazma mcp`

MCP server on stdio exposing the whole tool registry (155 tools) to any MCP client — Claude Desktop, an editor, another agent. tools/call hands straight to LocalToolRegistry.execute(), the same chokepoint where commitment authorization, PreToolUse hooks, the permissions allowlist and the HITL approval bus already live. Danger tools stop for a human through the same gate the chat window uses — that is the difference from kazma_gateway.mcp_server (“kazma-ide”), the older narrow IDE server whose check_sync() can only block, never queue. See docs/MCP_SERVER.md.

{
  "mcpServers": {
    "kazma": { "command": "kazma", "args": ["mcp"] }
  }
}

Env var	Meaning
`KAZMA_MCP_TOOLS`	Comma-separated allowlist, enforced on `tools/call` as well as `tools/list`.
`KAZMA_MCP_ALLOW_UNGATED`	Publish danger tools even with no verified approval path. Fail-closed is the default: ungated, danger tools are withheld entirely (155 tools become 100), not advertised and refused.

Tiers map onto MCP’s own destructiveHint / readOnlyHint, so danger tools render as destructive in the client’s approval UI without reading our docs.

2.9 `kazma doctor`

Answers “which model will this install use, and will it work?” (kazma_cli/doctor.py). It prints the active provider and model, the endpoint each request goes to, whether a usable key is there, and whether the model registry would switch to another provider. Exit code 1 when a check fails, 0 otherwise. It is read-only: it writes no settings and opens no connection.

kazma doctor

2.10 `kazma agent-skills`

Agent Skills (SKILL.md, the agentskills.io format) installed in the skill folders Kazma reads. A skill is checked when the model activates it, and every list shows the result of that check:

State	Meaning
`verified`	Signed by this install’s key and unchanged since. Loads.
`unsigned`	Never signed. Loads, with a warning in the log.
`refused`	Its content changed since it was signed, or another key signed it: `KAZMA_SECRET` changed, another Kazma install signed it (the user-level folder is shared), or someone re-signed it. Not loaded, and left out of the skill list the model sees.

Subcommand	Description
`kazma agent-skills list`	Every installed skill with its scope, state and source. A refused skill is followed by the reason and its folder.
`kazma agent-skills verify <folder>`	Check one skill. Exit code 1 when it would be refused.
`kazma agent-skills sign <folder>...`	Sign skills with this install’s key (writes `.kazma-install.json` beside each `SKILL.md`). Takes several folders; a folder without a skill is named and the rest are still signed. Sign only a skill you trust: signing is how you vouch for it.

kazma agent-skills list
kazma agent-skills sign ~/.agents/skills/my-skill ~/.agents/skills/other-skill

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). Kazma does not read these files yet: init creates them and show / validate check them, and no agent session uses them. Loading project rules into the agent is issue #20. (Until 2026-09-28 the generated rules.yaml said its rules were “applied to every agent session”.)

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`	Rebuild every chat adapter from the saved settings, as boot does (a saved setting applies on its own).

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; on a release-wheel install, reinstall the latest release
`--yes` / `-y`	Skip confirmation
`--reinstall` / `-r`	Packages/extras only (repair wiped venv): a checkout reinstalls from itself; a release-wheel install reinstalls its own release (tag `v<version>`), SHA-256 checked
`--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:

release wheel (pip-installed, no git checkout) → reads the newest GitHub release of Mubder/kazma, downloads its wheel from the release, and installs it (with the extras you already have) only when its SHA-256 matches the release’s SHA256SUMS and, where GitHub reports one, GitHub’s own digest of the file. Kazma is not on PyPI; kazma update never installs kazma from there. See SUPPLY_CHAIN.md.
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

A running server is stopped and started for you. The packages cannot be replaced while the server has them loaded. On an install the guard supervises, the update waits until no chat turn is running, has the guard stop Kazma and keep it stopped while the packages install, then starts it again. A failed install leaves Kazma stopped, and running the same command again is the repair. Without a guard, a running server is refused: stop it first. See Kazma update.

On Windows, run the installing forms with the install’s Python: .venv\Scripts\python.exe -m kazma_cli update --yes (or --reinstall -y). A reinstall must replace kazma.exe, and Windows lets nothing replace, or even rename, a launcher while it runs. Started from kazma.exe, or while kazma-tui runs, the update refuses before it installs anything and prints the command to use. --check installs nothing and runs anywhere.

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>`	Not implemented: says so and exits 2, installing nothing.
`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 the registry
kazma hub search "oil pricing" --capabilities mcp

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 in a connected chat app (Telegram, Discord, Slack). The full reference, with every subcommand and response, is Slash Commands; /help in any chat lists the same commands as Telegram’s ”/” menu.

Command	Description
`/help`	List commands by category.
`/sessions` · `/session <#>` · `/new`	List, take over or start a season (shared with the Web UI).
`/reset` · `/compact`	Clear the conversation, or compact its context now.
`/undo` · `/edit <text>`	Remove the last reply, or replace it with corrected text.
`/replay list \| <iter> \| compare <a> <b> \| clear` · `/fork <iter>`	Time travel: snapshots, rewind in place, compare, clear, branch.
`/steer <text>` · `/steer! <text>` · `/abort` (`/stop`)	Add to, interrupt or abandon the running task.
`/long` · `/mission` · `/yolo` · `/unrestricted`	Tool-round budget and approval bypass for this chat.
`/plan`	Plan mode: inspect and propose, execute on approval.
`/hitl approve \| deny \| approve_task`	Answer a pending approval from the chat.
`/model` (`/models`)	Show and switch the model (a picker on Telegram).
`/status`	Each chat app’s connection, the queue, messages in progress.
`/memory` · `/memory off \| on`	Facts held and whether this chat is remembered; keep it out of memory, or let it back in.
`/cost`	This chat’s tokens and cost, from the per-call ledger.
`/context`	How much of the model’s window this chat fills.
`/config` · `/personality`	Settings wizard; changing the model, memory, MCP servers or personality is admin-only.
`/research` · `/swarm` · `/ide` · `/kb` · `/documents` · `/skill`	Research, swarm dispatch, workspace, Knowledge Library, documents, Agent Skills.

Slack’s client runs /-commands itself, so on Slack approvals are answered with hitl approve or hitl deny, without the /. See Gateways & Platforms.

13. 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.”

kazma acquisition status [--job ID] [--json] [--language en|ar] reads cached local evidence. kazma acquisition credits explicitly refreshes Firecrawl account credits through the permitted remote route, then displays cached status. Settings and TUI expose the same explicit action. Unsupported charges remain unknown.

CLI Reference

1. Entry points

2. kazma — top-level tree

2.1 kazma (no args)

2.2 kazma status

kazma acquisition status

2.3 kazma serve [port]

2.4 kazma wizard

2.5 kazma docs

2.6 kazma ask [options] <prompt>

2.7 kazma acp

2.8 kazma mcp

2.9 kazma doctor

2.10 kazma agent-skills

3. kazma completion

4. kazma project

5. kazma gateway

5.0 The --port flag (swarm / gateway)

6. kazma swarm