Command reference
kagaz is a single binary. Every command accepts --json for a stable, documented shape, and mutating commands never change a vault without a preview and your approval.
Persistent flags
Available on every command.
| Flag | Meaning |
|---|---|
--vault <path> | Use this vault instead of discovering vault.yaml by walking up from the current directory. |
--json | Emit a stable, documented JSON envelope instead of human text — same underlying data, never a separate code path. |
--quiet | Suppress human progress output. Errors still go to stderr; the exit code is unchanged. |
--version | Print the kagaz version and exit. |
--yes / --accept-proposal | Approve a mutation non-interactively. |
--propose-only | Print the proposal and exit 0 without touching the vault. |
Commands
Read-only queries and reversible mutations, clearly separated.
| Command | Does |
|---|---|
kagaz init | Create a new vault (--fy-start, --root, --name, --demo). |
kagaz find | Query by person, company, area, doctype, tag, period, or free text. The read-only command agents lean on most. |
kagaz doctypes | List the doctype catalog this vault resolves to, with source and filed counts. |
kagaz ingest | OCR → classify → propose → (on approval) file, with a numbered batch review. --set-doctype to file an otherwise unclassified document. |
kagaz move | Relocate a document to its conventional path — SHA256-verified copy, tag/sidecar carry-over, staged source. |
kagaz tag | Add/remove Finder tags with --add/--remove, validated against the vault's controlled vocabulary. |
kagaz supersede | Mark a document replaced by a newer one; moves the lifecycle tag from active to superseded. |
kagaz lint | Report (and optionally --fix) convention violations. --fix applies only provably safe repairs. |
kagaz index | Regenerate INDEX.md and AGENTS.md from the tree and vault.yaml. |
kagaz rollback | Reverse any manifest a mutating command produced. Safe to run twice. |
kagaz resolve | Resolve a document reference to its current path. --for-send gates confidential documents behind explicit confirmation. |
kagaz log | Tail the append-only JSONL audit log. |
kagaz model pull | Download MLX classifier weights — the only network call in Kagaz. |
kagaz doctor | Check vault health and which optional tools/classifier backends are available. |
kagaz watch | Watch the vault and keep ingest proposals current, without auto-executing. |
kagaz mcp | Run the stdio MCP server. |
kagaz completion | Shell completion scripts. |
Exit codes
Part of the contract — a script may branch on these.
| Code | Meaning |
|---|---|
0 | Success. A refusal that is a real answer exits 0 too — e.g. ingest --propose-only that proposes nothing, or lint with only warnings. |
1 | A runtime failure: no vault found, a path that does not exist, a tag outside the vocabulary. |
2 | A bad invocation — unknown flag, missing argument. |
3 | A refusal to act without consent: resolve --for-send on a confidential document with no --confirm. No path is printed. |
4 | lint completed and found error-severity findings. Warnings and info alone still exit 0. |
1 and 3 is the one worth branching on: 1 means the command could not be carried out; 3 means it could and deliberately was not, pending a human.The confidential-send gate
Resolving a document tagged confidential for handoff outside the vault — attaching it to an email, uploading it, handing it to another tool — requires explicit confirmation and writes an audit line either way. With --json, resolve --for-send never prompts; it returns a structured response and a non-zero exit instead of a path:
An explicit --confirm supplies the consent an interactive prompt would gather, and only then does the command emit the resolved path and exit 0. The audit line is written on the confirmation_required response too — recording that resolution was attempted and not yet confirmed.