Reference › CLI reference

CLI reference

The doberman command (built with Typer) is how you check status, tune posture, recover from a lockout, and wire Doberman into a host. Every command and subcommand below accepts --help. This page groups them by what you use them for, then documents the JSON contract and exit codes that scripts can rely on.

Core commands#

Day-to-day posture, status, and review commands.

Auth enrollment#

Security-posture commands used by the setup guide. These groups also appear in doberman --help.

Note that the 2fa subcommands take no --path: TOTP enrollment is a device-wide factor, not a per-repo one.

Recovery#

Gated recovery actions for a stuck or compromised state. Each requires an enrolled possession factor (a 2FA code if enrolled, otherwise your Doberman password); with neither enrolled, the command fails closed.

Host hooks#

Wiring commands plus the low-level per-host handlers they install.

All four hook subcommands run only the fast deterministic objective floor, so they add minimal latency, and fail closed on any malformed input or engine error.

Output conventions#

Human-readable diagnostics use one severity vocabulary: error: means the command failed and returned a non-zero exit code, warning: means it succeeded but skipped or degraded something, and note: marks a purely informational aside. Machine-readable flags keep their documented schemas and never add these prefixes.

Machine-readable output#

Four flags cover every scriptable surface: --json (status, scan, doctor, policy-history, tune, memory) for one JSON document, --jsonl (log) for one redacted object per line, --quiet/-q (scan) to suppress the human map while keeping the exit code, and --path/-p (most commands) for the repository root, default .. When both --json and --quiet are passed to scan, --json wins.

Flag naming#

• --json emits one JSON object or array you can pipe directly into jq or python -m json.tool.
• --jsonl emits JSON Lines: each line parses independently, and an empty result set produces empty stdout, not []. This shape suits streaming consumers and while read line shell loops.

Stdout purity#

When a machine-readable flag is active, stdout contains JSON and nothing else. Tables, headings, spinners, and note:/warning: lines are suppressed or sent to stderr instead. Scripts should read only stdout; a human reads stderr.

Redaction guarantee#

JSON output never contains a raw file path, file content, argument value, environment variable, secret, or prompt text. It contains only what the human view already shows: path classes (*.env, backend/auth/*.ts), reason-code names, risk levels, and verdicts, because both views draw from the same already-redacted data.

Determinism guarantee#

Every --json document uses deterministic key ordering (sort_keys=True) and compact separators. Two invocations against identical state produce byte-for-byte identical output. --jsonl lines are deterministic per line, in the command's documented row order (newest first for log).

doberman scan --json schema#

{
  "version": 1,
  "path": ".",
  "capabilities": [
    {
      "name": "shell",
      "category": "tool",
      "present": true,
      "risk": "high",
      "evidence": ["path classes or tool names, never file contents"]
    }
  ]
}

Capabilities are sorted by (category, name) for deterministic output. Each capability's evidence list is capped at 10 entries in discovery; the human-readable risk map shows only the first 3 of those per capability, so scan and scan --json can legitimately show different amounts of evidence for the same capability.

doberman doctor --json#

Emits {version, path, ok, checks[], critical_failures[]}. ok is true only when every critical check (host hooks, config, decision DB) passed. Exit code stays non-zero when a critical check fails, even though the payload still prints.

doberman log --jsonl#

One redacted JSON object per decision line, newest first. Fields are an allowlist of already-redacted data: ts, final_verdict, action_type, target_path_class, reason_codes, auth_result, plus id, agent_role, and risk when present. Empty stdout when there are no rows.

doberman policy-history --json schema#

A JSON array of policy-change rows in newest-first order: each element carries the change timestamp, the changed key, the previous and new values, and the actor. No raw policy content, secret, or file path appears.

doberman tune --json#

Emits {version, decisions, sessions, unsessioned_decisions, interventions, interventions_per_session, top_auth_reason_codes, approval_rate_by_reason, approval_rate_by_target, trend, proposals}, deterministic for identical inputs and scoped to the most recent --last decisions (default 2000). A proposal looks like {id, kind, action_type, target_path_class, occurrences, approval_rate, reason_codes, ttl_days, what_would_loosen, why}; Doberman emits one only when a group has at least --min-occurrences (default 5) AUTH rows, all approved, a narrow non-whole-tree path class, and reason codes that are a non-empty subset of {role_out_of_scope}, the only code a standing elevation may cover. doberman tune never applies a proposal by itself. --accept <id> recomputes proposals from the same --last/--min-occurrences, rejects an unknown or stale id, then routes the accepted one through the same possession-factor-gated weaken chokepoint every other policy loosening uses before granting a revocable, time-limited elevation (doberman revoke <elevation-id> reverses it early).

Exit codes#

Every command follows a two-value convention: the same code always means the same class of failure, regardless of which command raises it.

Code 2 is reserved for input-validation failures that could be caught before any I/O or gate check runs, so a script can branch on "bad flag" versus "gate denied." Code 1 covers everything else: auth denials, runtime errors, missing optional extras, and partial-success failures.

Per-command detail#

Commands not listed (scan, review, status, log, policy-history, install-hooks, uninstall-hooks, session-summary, version, memory, setup, hook pre/post/openclaw/codex-pre) exit 0 on success and rely on Typer's default handler to return 1 on an unhandled exception; they have no typer.Exit(code=...) call sites of their own.

Collision audit#

grep -n "typer.Exit(code=" src/doberman/cli/main.py returns 45 call sites: 6 use code=2 (all input-validation rejections, checked before any gate runs) and 39 use code=1. No command uses both codes for the same logical condition, and no two commands use the same code for contradictory meanings. This section documents the count; it changes no exit-code value.

Examples#

doberman scan --path . | less
doberman scan --json | jq '.capabilities[] | select(.present)'
doberman scan --quiet; echo $?
doberman doctor --json | jq .ok
doberman policy-history --json | jq 'length'
doberman log --jsonl | jq -c 'select(.final_verdict=="block")'
doberman tune --json | jq '.proposals'
doberman 2fa setup
doberman password set
doberman setup

See also the setup guide and the root README.