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

It also lists approvals waiting to be used by an agent. An approval is redeemable once, by the next matching call, and expires after fifteen minutes by default — so it is worth being able to see one before it lapses.

where

bash

shotoku where

Prints the policy and ledger this directory resolves to, what decided each one, and whether the file exists yet.

text

Working directory  /Users/you/projects/agent
Shotoku home       /Users/you/.shotoku
Config file        /Users/you/projects/agent/shotoku.config.json

Ledger
  path    /Users/you/projects/agent/data/decisions.jsonl
  from    config file /Users/you/projects/agent/shotoku.config.json
  status  exists

Reach for this whenever a command shows less than you expect. An empty history and a history you are not looking at read identically otherwise — which is exactly what happens when your MCP server writes to one ledger and your terminal reads another.

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 →

ui

bash

shotoku ui [--port 4402] [--policy <path>] [--ledger <path>]

Serves a local dashboard on 127.0.0.1: pending approvals with Approve and Deny, budgets against limits, the full history, and the ledger's integrity. It prints a link with a per-run session token. See the dashboard guide →

bash

shotoku telegram [--ledger <path>]

Sends each new pending decision to your Telegram with Approve and Deny buttons, and records your answer with via: telegram:<id>. Reads SHOTOKU_TELEGRAM_BOT_TOKEN and SHOTOKU_TELEGRAM_CHAT_ID; without the chat ID it runs in setup mode and prints it. See Approve from your phone →

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 →