CLI reference

Every command, flag, and exit code. All commands read from shotoku.config.json by default. Flags override the config file.

Global flags

These flags are available on every command and override the values in shotoku.config.json.

Flag	What it does
--policy <path>	Path to the policy YAML file
--ledger <path>	Path to the decision ledger (JSONL)

Precedence order: CLI flags → environment variables → config file → built-in defaults (policy.yaml and data/decisions.jsonl).

init

bash

shotoku init [--dir <path>]

Scaffolds Shotoku in the target directory (defaults to the current directory). Creates three things:

shotoku.config.json — points to the policy file and ledger path
policy.yaml — a starter policy with OpenAI and Anthropic allowlisted
data/ — directory where decisions will be recorded

Safe to re-run — it will not overwrite existing files.

authorize

bash

shotoku authorize --actor <id> --action <action> --resource <resource> [--amount <n>]

Evaluates a single request against your policy and local ledger. Records the decision.

Flag	Required	Description
--actor	yes	Agent identifier
--action	yes	One of: `purchase`, `api_call`, `execute_code`, `send_email`, `mcp_tool`, `custom`
--resource	yes	Target domain or service (e.g. api.openai.com)
--amount	no	Monetary amount in USD. Must be non-negative if provided.

Exit codes: 0 if approved, 1 if denied or pending.

status

bash

shotoku status

Shows all decisions currently waiting for human review, plus the most recent decision. Each pending entry includes the actor, resource, amount, age, and a hint to approve or deny.

bash

shotoku status --ledger ./path/to/decisions.jsonl

history

bash

shotoku history [--actor <id>] [--since <window>] [--status <status>]

Lists past decisions as a formatted table with ✓ / ✗ / ◷ icons and a summary line.

Flag	Values	Description
--actor	any string	Filter to decisions made by this actor
--since	24h · 7d · 30d	Rolling time window to filter by
--status	approved · denied · pending_approval	Filter by decision outcome

bash

shotoku history --since 24h --status denied

decision

bash

shotoku decision <id>

Shows the full record for a single decision — the original request, outcome, all reasons, and any associated approval or denial that followed.

bash

shotoku decision dec_f3f0a6da3a69

approve

bash

shotoku approve <id>

Approves a pending decision. Shotoku appends a new approval record — it never modifies the original decision. Both are preserved in the local ledger.

Fails with a clear error if the decision does not exist, is not pending, or was already actioned.

deny

bash

shotoku deny <id>

Denies a pending decision. Same constraints and append-only behavior as approve.

tui

bash

shotoku tui

Launches the interactive terminal UI. Polls the ledger every 3 seconds and lets you navigate pending decisions with the keyboard. See the TUI guide →

snapshot

bash

shotoku snapshot create [--out <path>] [--key-id <label>]
shotoku snapshot verify --snapshot <path>

Creates and verifies cryptographically signed snapshots of your policy and ledger. Requires the SHOTOKU_SNAPSHOT_SECRET environment variable. See the Snapshots guide →