cli reference

Mizukara has five commands: onboard, gateway run, chat, scan, and replay.

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

---

mizukara onboard

Sets up ~/.mizukara/: writes config.json and generates a gateway bearer token. Refuses to run if a config already exists (delete ~/.mizukara/config.json to redo).

mizukara onboard [--ollama-only] [--approval-policy always-ask|allowlist|yolo]

• --ollama-only - skip provider API key prompts entirely; the config is set up for a fully local model, no keys stored anywhere.
• Without --ollama-only, prompts for an Anthropic / OpenAI / OpenRouter key each (blank to skip). Keys themselves are never written to config - only a marker like env:ANTHROPIC_API_KEY is stored, and mizukara reads the real key from that environment variable at call time.
• --approval-policy - default always-ask. See ApprovalPolicy in core/config.py for the other two (allowlist, yolo).

Prints the gateway token to stdout on success. That token is required for every authenticated gateway request (Authorization: Bearer <token>).

mizukara gateway run

Starts the FastAPI gateway daemon (see ARCHITECTURE.md for the endpoint list).

mizukara gateway run [--host 127.0.0.1] [--port PORT] [--expose]

• Refuses to start if mizukara onboard hasn't been run.
• Refuses to bind any host other than 127.0.0.1 unless --expose is also passed - this check happens before the server starts, not as an afterthought.
• --port defaults to the port chosen at onboard (config.gateway_port).
• Writes to ~/.mizukara/trails/gateway.jsonl for the lifetime of the process; the trail resumes correctly across restarts (see ARCHITECTURE.md - trails section).

Run this in the background (&, a separate terminal, or tmux) - it blocks in the foreground like any uvicorn.run() call.

mizukara chat

A minimal single-turn TUI client against a running gateway.

mizukara chat

• Requires onboard to have run (reads the gateway token and port from config).
• Loops: prompts >, POSTs to /v1/chat, prints the JSON response - the routing decision for your message. Full model replies are coming next; see Status.
• Exits with an error if it can't reach the gateway (Could not reach gateway. Is \mizukara gateway run` running?`).

mizukara scan <address>

Runs the exact same rule engine the public watchdog instance would, locally, against chain 4663. No gateway required - this one runs standalone.

mizukara scan <address> [--at-block N] [--out PATH]

• --at-block N - pin the scan to a specific block height instead of the chain's latest. This is what makes a scan reproducible: re-running the same address at the same block should produce a byte-identical artifact_sha256.
• --out PATH - write the artifact JSON to a file instead of printing to stdout.
• See RULES.md for exactly what gets checked, and ARCHITECTURE.md for the artifact's JSON shape.

Example:

$ mizukara scan 0x6CA3093cE4aC7c23E975093Cbf52E2fE9bf17777
{
  "mizukara_version": "0.1.0",
  "target": "0x6CA3093cE4aC7c23E975093Cbf52E2fE9bf17777",
  "chain": 4663,
  "block": 11688500,
  "rules": [ ... R1 through R5, each with id/verdict/facts ... ],
  "artifact_sha256": "..."
}

mizukara replay <trail>

Verifies a trail file's hash chain and re-checks recorded tool/provider call hashes. See "Replay" in ARCHITECTURE.md for exactly what this does and doesn't prove.

mizukara replay ~/.mizukara/trails/gateway.jsonl

Output:

chain_ok=True events=2

or, if tampered:

chain_ok=False events=2
reason: event_hash does not match recomputed hash
  [0] tool_call: verified - recorded output hash matches

Exit code is 0 only if the chain verified and every event replayed cleanly (ReplayReport.ok); otherwise 1 - safe to use directly in a script or CI check.