doberman

doberman [-V] command [options]

doberman is the command-line interface for Doberman, an adaptive authorization layer for coding agents. It sits on the execution path (a host PreToolUse hook or a transparent MCP proxy) and gives every tool call one verdict before the call runs: PASS (allow), AUTH (pause for human approval), or BLOCK (never execute). Uncertainty denies. Policy can auto-tighten; a permanent loosening needs an enrolled possession factor (TOTP if set up, otherwise the local Doberman password).The PyPI distribution is doberman-core. The bare doberman name on PyPI is an unrelated, abandoned project. After install the command and import name are still doberman. Python 3.11+ is required. Status is alpha (package 0.18.1 at documentation time). Apache-2.0.doberman setup is the Claude Code path: pick a mode, persist preference weights, and write hooks into .claude/settings.json (or ~/.claude/settings.json with --global). doberman install-hooks --host codex wires Codex CLI instead. For Claude Desktop, Cursor, or any MCP client, register doberman serve -- downstream-server as the MCP command; the agent client spawns the proxy. OpenClaw uses doberman hook openclaw via the in-repo adapter.Modes are light, balanced (default), strict, and paranoid. Hard blocks (secret exfiltration, destructive commands, role-boundary violations, confirmed read-then-send) are the same in every mode. The mode dial only changes when ambiguous or high-risk actions step up to AUTH. Orthogonal to mode is the enforcement dial: enforce (default), monitor (record discretionary verdicts, do not prompt), or off (skip the discretionary layer). The objective floor stays live in every state. Hand-editing enforcement: off in policies.yaml without a matching ledger entry is clamped back to enforce.Verdicts are colour-coded (BLOCK red, AUTH amber, PASS green) on review, status, log, the TUI, and demo. Colour is dropped when output is piped or NO_COLOR is set. Diagnostics use error:, warning:, and note: prefixes.

-V, --version

Print the installed version and exit (eager).

Repository root whose .doberman/ policy governs the command (default .). On serve, the same flag selects the policy root.

Accept defaults / skip typed confirm on setup, review, and uninstall. Never skips a possession-factor check.

Machine-readable output on doctor, status, scan, policy-history, tune (--json) or log (--jsonl).

Which harness install-hooks / uninstall-hooks edit.

Typer shell completion installer (after pip install).

.doberman/

Per-repo control plane (not committed). policies.yaml holds mode, enforcement, preference weights, and the policy checklist. role.yaml is an optional explicit role (wins over role enable-default). Decision DB, taint, and tool pins live here too.

Optional HTTPS sink for redacted decision records. auth_env names an environment variable sent as Authorization. Delivery is best-effort and never blocks a verdict.

Optional post-fetch sha256 pins. Unpinned artifacts are not verified.

Device-wide password / TOTP enrollment, fingerprint key, and metrics.db. Shared across every project on the machine.

Set to off to disable the optional pre-inference turn gate (MCP-proxy deployments without a host pre-inference hook already omit it).

Set to 1 (and install doberman-core[explain] with ANTHROPIC_API_KEY) to let the TUI rewrite a verdict's "why" in plainer language. The model is a narrator only; any failure falls back to the offline template.

Non-empty value drops colour from CLI output.

setup [-y] [-m mode] [-g] [-p path]

First-run wizard for Claude Code: choose mode, optionally tune preference weights, write hooks. -y accepts balanced and project-scope hooks with no prompts.

Idempotent hook install. Default host is Claude Code (PreToolUse, PostToolUse, SessionStart). --host codex writes doberman hook codex-pre into hooks.json.

Remove only Doberman hook entries. Does not delete .doberman/ or device-wide auth. Run this before pip uninstall doberman-core.

Project-scoped removal of project/local hooks and .doberman/. Requires a possession factor; -y skips the typed directory-name confirm, never the factor check. Leaves --global hooks and ~/.doberman/ alone.

Read-only health check (hooks, config, decision DB, 2FA, enforcement, fingerprint key). Exit 1 if a critical check fails.

Role, mode, prefs, policy summary, hook install state, taint, elevations, last decisions.

Read-only capability risk map (sensitive files by name only). --mcp statically admits repository MCP configs; reports pattern classes, never raw URLs or env values.

Print the recommended policy checklist. -y writes .doberman/policies.yaml. Core hard blocks cannot be disabled here.

Print or set security mode. Lowering requires a possession factor; raising applies immediately.

Print or set the enforcement dial. Softening is gated and ledger-verified.

Print the SL5 weights (confidentiality, reversibility, interruption_tolerance, blast_radius, each in [0, 1]) or set one. Lowering a weight is gated. The objective floor never moves.

Opt in to (or gated opt out of) the packaged least-privilege coding-assistant role when no .doberman/role.yaml exists.

Append-only policy-change ledger, including denied weakenings.

Recent redacted decisions (path class, reason codes, verdict, auth result). No raw targets or secrets.

Interactive log browser. Needs pip install "doberman-core[tui]".

Localhost-only dashboard (default 127.0.0.1:8642) with a single-use URL token. Needs pip install "doberman-core[dash]".

Scripted attack reel through the real engine. Nothing is executed or prompted. Exit 1 if an expected verdict mismatches.

Print-and-exit device-wide lifetime rollup from ~/.doberman/metrics.db. Always exits 0. Hidden alias: dashboard.

MCP stdio proxy in front of server. Logs go to stderr; stdout is the MCP channel. Do not run this by hand to "start" an agent — the MCP client spawns it.

Host hook entrypoints (JSON on stdin). Wired by install-hooks; not meant to be typed interactively.

Enroll or rotate the local password possession factor.

Enroll TOTP (prints a provisioning URI), drop it (proves the current code), or clear a lockout (proves the password).

Gated wipe of this repo's secret-read taint and read-vs-send fingerprints.

Gated re-pin of a changed MCP tool schema after out-of-band review.

Redacted learned-memory summary; gated wipe; ungated retention prune (does not touch the decision log).

Friction report. --accept grants a time-limited standing elevation through the same weaken gate. Reverse with revoke.

Revoke an active role elevation (see status).

Print the installed version (same as -V).

This is the fu351 agent-guardrail CLI, not an unrelated PyPI project also named doberman. Host hooks run only the deterministic objective floor (no adaptive/subjective layer); that layer currently requires the MCP proxy path. Static egress classification can miss runtime-built hosts, nested shells, DNS-label exfil, and /dev/tcp. Unanswered AUTH times out to a denial (2 minutes for the desktop dialog, 20 minutes as the backstop). A human at the keyboard can still disable host hooks. Uninstall the hooks before uninstalling the package, or every gated tool call fails with doberman: command not found.

claude(1), codex(1), openclaw(1), cursor(1), pip(1), npx(1)

Source code · Documentation