CLI commands
Every defenseclaw verb, grouped by what you are trying to do — first run, setup, audit, scanning, gateway control, status, uninstall.
Authoritative source for any flag is defenseclaw <command> --help. These groupings are curated for browsing.
Command availability is platform-specific
A registered command or connector alias is not, by itself, a native Windows support claim. Native Windows certifies Codex, Claude Code, and Amp, and some commands require optional configuration or are unavailable there. Use the native Windows command matrix for the certified Windows classification and safe examples.
DefenseClaw ships two binaries:
defenseclaw— the operator-facing Python CLI. Entry point forinit,setup,audit,policy,skill/mcp/pluginscans, alerts, doctor, etc.defenseclaw-gateway— the long-running Go sidecar. Owns the on-host daemon (start/stop/restart), policy reload, code scanning, and the audit-DB JSONL exporter.
Tables below tag each row with the binary that owns it.
First run
| Command | Use it for |
|---|---|
defenseclaw init | Interactive first-run wizard. On a TTY, pre-selects installed hook connectors and lets you choose which ones stay observe vs action. Non-interactive multi-connector flags are --observe-all and --action-connectors; an explicit --connector keeps the single-connector path. |
defenseclaw quickstart | Zero-prompt first-run for one connector with safe defaults. Pass --connector <name> when more than one connector is configured or detected. See Quickstart. |
defenseclaw doctor | Health and repair check. Run this first whenever something feels off; see Doctor below. |
defenseclaw status | Enforcement flags and gateway state, plus a per-connector block for every active connector. Read commands like this fan out to all actives — the same layout whether one or N are wired. |
Doctor
defenseclaw doctor [--json-output | --json] [--passive]
defenseclaw doctor --fix [--dry-run] [--yes] [--fix-id REPAIR_ID]...Common invocations:
defenseclaw doctor --json
defenseclaw doctor --passive
defenseclaw doctor --fix --dry-run
defenseclaw doctor --fix --fix-id doctor.gateway.token.ensureDoctor checks configuration, audit and identity state, component and active connector compatibility, scanner binaries, managed gateway health and authentication, configured guardrail and scanner services, credentials, and observability destination health.
--json-output (also available as --json) emits schema v2. Health remains in
checks and summary; repair attempts are independent records under repairs
and repair_summary. Repair states are applicable, noop, blocked,
manual, requires_confirmation, declined, applied, and failed. Each
record also carries its stable repair ID, risk, dependencies, effects, blockers,
restart potential, and platform. The top-level outcome and exit_code
combine health and repair results without adding repair failures to health
counters.
Use --passive to suppress synthetic telemetry, LLM, and
inspection-content-submitting probes. Every --fix --dry-run is passive and
runs planners only, so it cannot mutate disk or restart a service.
--fix-id is repeatable and selects exact work plus declared dependencies.
--yes may approve eligible safe and disruptive repairs, but does not select
policy or experimental work. A JSON repair must be a dry-run preview or include
--yes. See Reporting and diagnosis
for token, audit, identity, compatibility, and recovery safety boundaries.
Setup
Hook setup aliases (setup codex, setup claude-code, setup hermes, and the rest) add or reconfigure one connector. On a host with another hook connector already active, choose Add to join the active roster; choose Replace only when you want to return to one wired connector. Proxy connectors (openclaw, zeptoclaw) own the traffic plane and do not join the hook-connector roster.
| Command | Use it for |
|---|---|
defenseclaw setup guardrail | The central setup command. See Setup Guardrail. |
defenseclaw setup llm | Write the unified or role-scoped LLM block (--role unified|agent|judge). Supports SaaS providers and regional Bedrock / Vertex AI / Azure OpenAI via dedicated --bedrock-*, --vertex-*, --azure-* flags, plus --instance-name to bind a custom-provider overlay and --inherit-from to seed from a sibling component. Pair with --ping for an immediate reachability probe. See Unified LLM key. |
defenseclaw setup provider add|list|show|remove | Manage the ~/.defenseclaw/custom-providers.json overlay used to route LLM traffic through internal or self-hosted endpoints. add accepts --base-url, --domain (repeatable; required alongside --base-url so the gateway can match inbound URLs back to this overlay entry — defenseclaw doctor warns when the base_url host is not covered), --base-provider-type, --env-key, --allowed-request, --available-model, --request-path-override, TLS knobs (--ca-cert-file, --insecure-skip-verify), and provider-typed regional flags: Bedrock — --bedrock-region, --bedrock-auth-mode, --bedrock-access-key-env, --bedrock-secret-key-env, --bedrock-session-token-env, --bedrock-profile-name, --bedrock-inference-profile, --bedrock-deployment alias=model-id (repeatable); Vertex AI — --vertex-project-id, --vertex-region, --vertex-auth-mode, --vertex-service-account-json-env; Azure OpenAI — --azure-endpoint, --azure-api-version, --azure-auth-mode, --azure-deployment-alias model=deployment (repeatable). Each family is rejected against a mismatched --base-provider-type. Omit --name interactively for the wizard. |
defenseclaw setup claude-code | Hook setup alias for Claude Code; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup codex | Hook setup alias for Codex; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup cursor | Hook setup alias for Cursor; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup windsurf | Hook setup alias for Windsurf; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup geminicli | Hook setup alias for Gemini CLI; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup copilot | Hook setup alias for GitHub Copilot CLI; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup hermes | Hook setup alias for Hermes; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup openhands | Hook setup alias for OpenHands; defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup antigravity | Hook setup alias for Antigravity (agy); defaults to observe, pass --mode action to block hook-side. Returning decision=ask from the hook overrides agy's --dangerously-skip-permissions flag. |
defenseclaw setup opencode | Hook setup alias for OpenCode; writes the auto-loaded bridge plugin. Defaults to observe, pass --mode action to block hook-side. |
defenseclaw setup amp | Direct-to-upstream system-policy setup for Amp; writes the TypeScript plugin. Defaults to observe; pass --mode action for synchronous tool.call execution gating and model-bound tool.result output gating. Native confirmation is available only in the active foreground thread; background confirmation falls back to safe rejection or withholding. |
defenseclaw setup omnigent | Hook setup alias for OmniGent; installs the custom Python policy bridge. Defaults to observe, pass --mode action for ALLOW/ASK/DENY enforcement. |
defenseclaw setup openclaw | Full guardrail alias for OpenClaw (proxy connector). |
defenseclaw setup zeptoclaw | Full guardrail alias for ZeptoClaw (proxy connector). |
defenseclaw setup local-observability up|down | Bring up the bundled Prom/Loki/Tempo/Grafana stack. |
defenseclaw setup galileo [status|test|enable|disable|remove] | Configure and verify Galileo Cloud or self-hosted OTLP traces. |
defenseclaw setup splunk | Configure local Splunk in Docker, Splunk Enterprise HEC, or Splunk Observability Cloud. |
defenseclaw setup webhook | Configure Slack / PagerDuty / Webex / generic notifier webhooks (chat + incident routing). |
defenseclaw setup observability add|list|enable|disable|remove|test | Manage config-v8 destinations across OTLP, Galileo, Splunk HEC, JSONL, HTTP JSONL, console, and Prometheus capabilities. Omitted destination policy means all supported signals/buckets, unredacted. Distinct from setup webhook, which manages notifier webhooks. |
defenseclaw setup redaction [status|remove-all|apply|defaults|bucket|profile|destination|route] | Configure v8 redaction interactively or with scriptable subcommands. Bare invocation offers a simple baseline choice followed by Show advanced settings? for all buckets, profiles, destination policy, and ordered routes. Mutations preview the canonical effective diff; changed non-dry-run writes create a timestamped backup and verify the installed plan. |
defenseclaw observability plan | Print the masked effective v8 graph: generated local SQLite policy, collection, destination capabilities, routes, profiles, retention, and warnings. |
For observability destinations, name is the stable identity: a new name adds,
and an existing name updates only that destination. Run list --json for the
complete target/kind/signal inventory and add ... --dry-run for a safe preview.
The TUI mirrors the runtime-loaded inventory in Overview → Observability
Destinations and exposes the wizard at 0 Setup → Observability / Galileo.
The quickest way to remove every configurable redaction override is:
defenseclaw setup redaction remove-all --dry-runProfile none permits governed content without redaction
remove-all can expose governed content to configured destinations. Confirm that
each affected destination has an approved trust boundary before using --yes.
defenseclaw setup redaction remove-all --yesThis selects profile none for configurable log and trace projections without
changing collection or routing. It affects generated local SQLite, but never
weakens the release-owned managed enterprise destination. See
Redaction for the full interactive walkthrough and
advanced command examples.
| Command | Use it for |
|---|---|
defenseclaw setup trusted-paths list|add|remove | Manage the directories trusted for connector-binary version probing (action-mode setups refuse binaries outside this allow-list). list shows built-in defaults plus operator additions with source and status; add validates the directory (world-writable / relative paths refused unless --force) and persists to ~/.defenseclaw/.env; remove only touches operator-added entries. All verbs accept --json. |
Safety gates are intentional
Commands that fetch remote content fail closed when the trust boundary is
unclear. Connector version probes enforce trusted path prefixes when
ai_discovery.require_trusted_binary_paths: true; that gate defaults to
false for on-demand discovery. Registry and scanner fetches reject loopback,
link-local, cloud-metadata, and private-network targets unless explicitly
allowed; defenseclaw upgrade verifies release artifacts before stopping the
running gateway.
Guardrail
Per-connector guardrail controls. --connector X is the explicit scope selector on a multi-connector install: reads narrow to one active connector, and writes land in guardrail.connectors.<name>. Omit --connector for the broad path. Reads show the full active roster; global enable/disable affects the whole guardrail; fail-mode, HILT, and block-message writes reconcile active connector posture where supported. On a single-connector install --connector is rejected because there is only one posture. All of these are on the Python defenseclaw CLI.
| Command | Use it for |
|---|---|
defenseclaw guardrail status [--connector X] | Read-only. Shows the resolved guardrail posture (enabled, mode, fail mode, HILT, block message) as one per-connector block for every active connector by default. Pass --connector X to narrow the view to one active connector. |
defenseclaw guardrail enable [--connector X] | Turn the guardrail on. Global, or re-enable a single previously-disabled connector (restores its hooks with no re-prompt). |
defenseclaw guardrail disable [--connector X] | Kill switch. Global disables everything; --connector X drops just that connector from the active set and removes its hooks. |
defenseclaw guardrail fail-mode [open|closed] [--connector X] | Show/set behavior for hook delivery, authentication, and invalid-response failures. Run bare it prints the global value plus a per-connector breakdown of every active connector's effective value. See Reference → Fail modes. |
defenseclaw guardrail hilt [on|off] [--min-severity high|medium|low|critical] [--connector X] | Show/set human-in-the-loop approval policy. Run bare it prints the global value plus a per-connector breakdown. |
defenseclaw guardrail block-message "<text>" [--connector X] | Show/set the message the agent sees when an action is blocked. Run bare it prints the global value plus a per-connector breakdown. |
defenseclaw guardrail status # full per-connector roster
defenseclaw guardrail status --connector codex # one connector's resolved posture
defenseclaw guardrail fail-mode closed --connector codex # scope to one connector
defenseclaw guardrail hilt on --min-severity HIGH --connector claudecode
defenseclaw guardrail disable --connector codex # then `enable --connector codex` to restoreSee Setup → Multi-connector for the full multi-connector model.
Multi-connector
One gateway can protect N hook connectors at once (see Setup → Multi-connector). That splits the CLI into a few contracts:
- Read / status / inventory — fan out to all active connectors.
defenseclaw status,defenseclaw doctor, baredefenseclaw guardrail status, the bareguardrail fail-mode/hilt/block-messagereads, and the list/status commands (skill list,mcp list,plugin list,tool list,tool status,codeguard status) render every active connector where applicable. Use--connector Xon commands that expose it to narrow the view. - Mutating guardrail commands —
--connectormeans one connector.guardrail enable/disable/fail-mode/hilt/block-messagechange one connector when given--connector X. Omit it for the broad path: enable/disable is global, while fail-mode, HITL, and block-message reconcile active connector posture where supported. - Asset policy/config commands — default broad,
--connectorscoped.skill,mcp,plugin, andtoolpolicy verbs write broad fallback state by default and one connector's scoped state with--connector X. Config/install verbs such asmcp set,mcp unset,skill install,plugin remove, andcodeguard installoperate across configured/active connectors by default and narrow with--connector X. - Scan commands — default to configured/active connectors, narrow with flags.
skill scan --all,mcp scan --all,plugin scan --all, andaibom scancover configured/active connector sources by default; pass a positional target and--connector Xwhere supported to scope to one.
These list/inventory verbs read across the full active roster:
| Command | Default scope |
|---|---|
defenseclaw skill list [--connector X] | All active connectors by default; one connector when scoped. |
defenseclaw mcp list [--connector X] | All configured connector MCP sources by default; one connector when scoped. |
defenseclaw plugin list [--connector X] | All configured connector plugin sources by default; one connector when scoped. |
defenseclaw tool list/status [--connector X] | Effective tool policy for all active connectors by default; one connector when scoped. |
defenseclaw codeguard status [--connector X] | CodeGuard install state across active connectors by default; one connector when scoped. |
Audit & alerts
| Command | Use it for |
|---|---|
defenseclaw tui | Interactive Textual dashboard — audit, alerts, logs, inventory, and setup panels. The recommended live view. |
defenseclaw alerts [--connector X] | Snapshot of recent alerts (default 25) as a table. --connector X filters by per-event connector attribution; --limit N widens the scan window, and --show <n> prints the full record. |
defenseclaw alerts acknowledge / dismiss | Acknowledge or dismiss alerts (writes an audit_log_activity mutation). --severity all|CRITICAL|HIGH|MEDIUM|LOW. |
defenseclaw audit log-activity --payload-file <f> | Record a config/operator mutation through the gateway's audit logger. Used internally by the TUI on save. |
defenseclaw-gateway audit export | JSONL export of audit_events from the SQLite DB, including structured when structured_json is present. Rows are emitted oldest-first; --limit N therefore returns the earliest N matching rows, not the newest N. Omit --limit and pipe to tail for the most recent rows. --include-activity also dumps activity_events. |
tail -f ~/.defenseclaw/gateway.jsonl | jq | Tail the optional v8 JSONL destination when configured at that path. Mandatory local history is SQLite; JSONL is not an implicit mirror. |
AI discovery
agent discover is the fast, gateway-independent connector inventory. The
continuous scanner is a separate sidecar surface and is the one that inventories
local model APIs, known model caches, and standalone model files.
Enhanced mode expands the bounded roots searched for models; it does not relax what qualifies as a model. Outside recognized model stores, ambiguous ONNX/ORT, TFLite, PyTorch/checkpoint, and generic binary artifacts require explicit model context plus a meaningful, non-opaque identity. Known Chrome Optimization Guide cache payloads and opaque hash/version identities are suppressed, while high-signal formats and recognized model stores retain their established behavior.
| Command | Use it for |
|---|---|
defenseclaw agent discover [--refresh] [--no-cache] [--json] [--emit-otel/--no-emit-otel] | Inspect known connector configs and binaries without requiring the gateway. This does not run the continuous local-model scan. |
defenseclaw agent discovery enable [--mode passive|enhanced] [--scan-roots ROOTS] [--include-network-domains/--no-include-network-domains] [--lookup-model-provenance-online/--no-lookup-model-provenance-online] [--restart/--no-restart] [--scan/--no-scan] | Enable and tune the sidecar scanner. passive limits model-file coverage to known stores plus narrower configured roots and suppresses an exact user-home/~ root; enhanced also honors the broad home root and adds bounded macOS application-storage and app-resource roots for unknown applications. Vetted loopback model API reads follow include_network_domains; filesystem model discovery runs independently. Public Hugging Face lineage lookup is a separate opt-in because it transmits recovered model repository IDs. |
defenseclaw agent discovery setup|status|scan|disable | Configure discovery interactively, inspect on-disk/live state, trigger a full scan, or disable the service. |
defenseclaw agent usage [--refresh] [--detail] [--state STATE] [--category CAT] [--product NAME] [--component NAME] [--show-gone] [--by-detector] [--json] | Read the sidecar snapshot. Local-model rows show model ID, installed/loaded status, and format; --component also matches model IDs. active remains an alias for the steady seen lifecycle state. JSON output is the unfiltered API payload. |
defenseclaw agent processes [--refresh] [--json] [--limit N] | List live AI process signals with PID, user, command name, and uptime. |
defenseclaw agent components [--refresh] [--json] [--ecosystem ECO] [--name NEEDLE] | Show the deduplicated package/SDK component rollup and confidence scores. |
defenseclaw agent usage --refresh --category local_model --detail
defenseclaw agent usage --component Qwen3
defenseclaw agent usage --state seen
defenseclaw agent usage --show-goneSee AI Discovery for supported model servers, standalone file formats, lifecycle behavior, and privacy boundaries.
Scanning
The Python CLI exposes one scan group per asset family — there is no top-level scan group. Code-scanning lives on the Go gateway binary.
| Command | Binary | Use it for |
|---|---|---|
defenseclaw skill scan [target] [--connector X] [--all] [--path] [--remote] [--action] | defenseclaw | Scan a configured skill, a path, a URL (https://… / clawhub://…), or every configured skill with --all. A bare skill name searches matching configured connector copies; --connector X narrows. |
defenseclaw mcp scan [target] [--connector X] [--all] [--scan-prompts] [--scan-resources] [--scan-instructions] | defenseclaw | Scan one MCP server by name or URL, every configured server with --all, or every server on one connector with --connector X. |
defenseclaw plugin scan [name_or_path] [--all] [--connector X] [--profile default|strict] [--use-llm] | defenseclaw | Scan one plugin/extension package, or all discovered plugins with --all. --connector X narrows discovery or duplicate plugin names to one connector. |
defenseclaw aibom scan [--connector X] [--json] [--summary] [--only <cat>] | defenseclaw | Build the agent SBOM (skills, MCP, plugins, models, sinks) for every active connector by default, or one connector when scoped. |
defenseclaw registry sync [source...] [--all] [--scan] | defenseclaw | Sync registries; with --scan, runs the scanner pipeline against every fetched entry. |
defenseclaw codeguard {status,install,install-skill} [--connector X] | defenseclaw | Manage the CodeGuard skill/rule install across active connectors by default, or one connector when scoped. |
defenseclaw-gateway scan code <path> [--json] [--schema] | defenseclaw-gateway | Scan source files in <path> using the bundled CodeGuard rule pack. Runs the scanner in-process — does not require the sidecar daemon to be running. |
Asset Policy Commands
These commands are connector-aware because the same asset name can exist in more than one connector source. Bare commands keep the broad fallback behavior; --connector X writes or reads the connector-scoped state.
| Command | Use it for |
|---|---|
defenseclaw skill block|allow|unblock|disable|enable|quarantine|restore|install <name> [--connector X] | Manage skill policy, runtime disablement, quarantine, restore, and install. Without --connector, matching configured connector copies are handled together or the unscoped fallback is written; --connector X targets one connector copy. |
defenseclaw mcp set|unset|block|allow|unblock <name> [--connector X] | Manage connector MCP config and MCP admission policy. mcp set / unset write every configured connector source by default; --connector X writes one connector's MCP source. |
defenseclaw plugin remove|block|allow|unblock|disable|enable|quarantine|restore|info <name> [--connector X] | Manage plugin policy and runtime/file actions across configured connector copies by default, or one connector when scoped. |
defenseclaw tool block|allow|unblock|list|status <name> [--connector X] | Manage tool-level block/allow policy. Bare rows are the fallback tier for every configured connector; connector-scoped rows use the runtime-enforceable @connector/tool key. |
Gateway daemon
The sidecar is the Go binary; the Python CLI does not own a gateway group. Most operators never run these directly — defenseclaw setup * commands restart the sidecar implicitly when --restart is passed.
| Command | Binary | Use it for |
|---|---|---|
defenseclaw-gateway start | defenseclaw-gateway | Start the sidecar as a background daemon. |
defenseclaw-gateway stop | defenseclaw-gateway | Stop the running sidecar. |
defenseclaw-gateway restart | defenseclaw-gateway | Restart the sidecar. |
defenseclaw-gateway status | defenseclaw-gateway | Health snapshot of the running daemon. On a multi-connector install it also renders a per-connector "Connector Mode" section (one row per active connector) sourced from the /status endpoint's connector_modes array. |
defenseclaw-gateway policy reload | defenseclaw-gateway | Re-read OPA policies from disk without bouncing the daemon. |
defenseclaw-gateway watchdog [start|stop|status] | defenseclaw-gateway | Health-watchdog daemon that notifies when the gateway is down. |
tail -f ~/.defenseclaw/gateway.jsonl | jq | shell | Tail a configured kind: jsonl destination. It contains only records selected for that destination; mandatory complete local log history remains SQLite. |
TUI
| Command | Use it for |
|---|---|
defenseclaw tui | Open the interactive operator UI for audit, alerts, logs, inventory, and settings. It does not provide a resumable approval queue for hook calls. |
Upgrade
| Command | Use it for |
|---|---|
defenseclaw upgrade [--version X] [--yes] | Drive an upgrade under a compatible installed controller. It verifies artifacts before stopping services, backs up managed state, installs the CLI and gateway, runs release-owned migrations, refreshes owned local-observability assets, restarts services, and performs version-bound health checks. The immutable 0.8.4 built-in command cannot parse the truthful 0.8.5 manifest because that manifest has an empty Windows bridge matrix; a 0.8.3-or-older built-in command also cannot learn the two-process bridge handoff retroactively. To cross into 0.8.5, use the authenticated target-release POSIX resolver in latest mode without a version override. That resolver, and built-in controllers from 0.8.5 onward for later compatible manifests, can authenticate a temporary pinned Cosign when no system Cosign exists. --allow-unverified cannot bypass provenance. See Upgrade DefenseClaw. |
defenseclaw migrations status [--json-output] | Show the durable migration cursor and any drift between applied and release-required migrations. |
defenseclaw migrations unmark VERSION | Mark one migration for retry on the next upgrade. Use only as a targeted recovery action. |
defenseclaw migrations reset | Remove the migration cursor so the next upgrade bootstraps it again. This does not roll back configuration files. |
A source listed for its platform in the published-baseline matrix can upgrade to
latest through the authenticated current release-owned resolver, which selects
and health-checks 0.8.4 before starting a fresh bridge controller. Sources
outside that matrix fail closed with the exact supported path. Never force a
hard-cut version or rerun a fresh installer over an old installation.
Uninstall / disable
| Command | Use it for |
|---|---|
defenseclaw setup guardrail --disable | Roll back guardrail. Connector files restored from backup. |
defenseclaw uninstall | Reversible by default — runs connector teardown, stops the sidecar, removes the OpenClaw plugin, leaves ~/.defenseclaw/ (audit DB, config, secrets) intact. |
defenseclaw uninstall --all | Same as above, plus deletes ~/.defenseclaw/. Add --binaries to also remove the defenseclaw and defenseclaw-gateway binaries from ~/.local/bin. |
defenseclaw reset --yes | Wipe ~/.defenseclaw/ so defenseclaw quickstart starts clean — keeps binaries and the OpenClaw plugin in place. |
Discoverability
defenseclaw --help
defenseclaw setup --help
defenseclaw setup guardrail --help
defenseclaw audit --helpEvery command tree responds to --help. The CLI prints all flags, defaults, and a one-line description for each.
Reference
Lightweight reference index. CLI command index, gateway API surface, configuration files, and environment variables. Authoritative source for CLI flags is `defenseclaw <command> --help`.
Gateway API
The defenseclaw-gateway sidecar API — its registered route patterns, authentication and CSRF model, and inspection verdict shape. The handler code is authoritative.