CLI commands

Authoritative source for any flag is defenseclaw <command> --help. These groupings are curated for browsing.

DefenseClaw ships three binaries:

• defenseclaw — the operator-facing Python CLI. Entry point for init, setup, audit, policy, skill/mcp/plugin scans, 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.
• defenseclaw-acp — the protocol-aware stdio guard spawned by ACP clients. It validates its runtime contract before launching the selected agent, then evaluates ACP traffic while it mediates stdio.

Tables below tag each row with the binary that owns it.

First run

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.ensure

Doctor 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.

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-run

defenseclaw setup redaction remove-all --yes

This 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.

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, except for mode, block-at, alert-at, use-pack and protection, which accept the one active connector and write its override block. All of these are on the Python defenseclaw CLI.

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 block-message --clear --connector codex # inherit global / built-in
defenseclaw guardrail block-message --clear                # clear global + active overrides
defenseclaw guardrail disable --connector codex           # then `enable --connector codex` to restore
defenseclaw guardrail use-pack strict                     # every connector, clears overrides
defenseclaw guardrail use-pack ~/packs/my-org --connector codex
defenseclaw guardrail use-pack --clear --connector codex  # back to the global pack
defenseclaw guardrail mode action                         # every connector without its own mode
defenseclaw guardrail mode observe --connector codex      # codex only logs
defenseclaw guardrail block-at HIGH                       # every connector without its own level
defenseclaw guardrail block-at MEDIUM --connector codex   # codex blocks MEDIUM+
defenseclaw guardrail alert-at inherit --connector codex  # back to the global or rule-pack level
defenseclaw guardrail protection enable database-destruction-protection --connector codex

See Setup → Multi-connector for the full multi-connector model.

Tool-call levels

A tool call's finding is blocked at or above the block level and raises an alert at or above the alert level. Each level resolves on its own: the connector's guardrail.connectors.<name>.block_at / alert_at, else the global guardrail.block_at / alert_at, else the level the scope's rule pack implies (from its folder name: strict blocks MEDIUM+ and alerts on LOW+, permissive blocks CRITICAL and alerts on HIGH+, anything else blocks CRITICAL and alerts on MEDIUM+). The alert level is then lowered to the block level if it sits above it. A global level therefore also replaces a stricter pack's level on every connector without its own; the command names those. In observe mode nothing is blocked; the levels apply once the scope is in action mode.

block-at and alert-at --json print:

{
  "version": 1,
  "ok": true,
  "scope": "codex",
  "setting": "block_at",
  "level": "CRITICAL",
  "previous": "inherit",
  "source": "override",
  "effective_block_at": "CRITICAL",
  "effective_alert_at": "LOW+",
  "gateway": "restarted",
  "message": "Codex (codex) now blocks tool calls at CRITICAL. Restarted the gateway; it is enforcing the change now."
}

level and previous are the value the scope stores after and before the change (inherit when it has none; when the command fails, level is the one you asked for and nothing is written). source says where the scope's value of this setting comes from now: override (its own), global, or pack. effective_block_at and effective_alert_at are the scope's resulting levels (CRITICAL, HIGH+, MEDIUM+, LOW+).

Opt-in protection packs

The packs in policies/guardrail-use-cases/ (shipped with the package) add deterministic rules that only make sense where the operator declares a protected environment, for example that a connector's database really is production. See Protection packs for what each one covers. Enabling one tells DefenseClaw that the scope's environment is protected: it blocks what the pack proves there and never infers that from resource names.

guardrail protection enable NAME builds the scope's pack from its current base pack (a preset or a custom directory; a pack composed earlier is rebuilt from the base it records) plus every opt-in pack that is on, using Policy Creator's merge: the pack's rule IDs are removed from every base file, then its rules are appended to the file with the same name or added as a new file. The result goes to protected-global/ or protected-<connector>/ with a defenseclaw-pack.json manifest ({"version": 1, "base", "base_name", "protection": [...]}), is validated before anything points at it, and the scope is switched to it. The global scope doesn't touch connectors that have their own rule pack; it lists them under not_covered so you can enable the pack there too. A composition that fails validation, for example one that exceeds the semantic-rule cost ceiling, changes nothing.

protection enable|disable --json prints:

{
  "version": 1,
  "ok": true,
  "scope": "global",
  "pack_path": "/Users/me/.defenseclaw/policies/guardrail/protected-global",
  "protection": ["privacy-high-assurance", "cloud-production-protection"],
  "validation": {
    "wire_version": 1,
    "kind": "validation",
    "valid": true,
    "summary": {
      "judge_count": 4,
      "judge_category_count": 23,
      "rule_file_count": 8,
      "rule_count": 247,
      "enabled_rule_count": 243,
      "local_pattern_count": 11,
      "suppression_count": 9,
      "sensitive_tool_count": 6,
      "digest": "e9c55a1b691056955a3a2479b8eb694287dfb7b549cc869a01465e5583eaa5d5"
    }
  },
  "not_covered": ["codex"],
  "gateway": "restarted",
  "message": "Cloud production protection is on for the global rule pack (protected-global, on top of 'default'). Restarted the gateway; it is enforcing the change now."
}

protection list --json prints {"version": 1, "packs": [...], "scopes": [...]}. Each pack has name, title, summary (the README's first paragraph), covers (a short phrase), rule_count, rule_ids, status (selectable or staged), and rules (id, severity, title). Each scope has scope (global or a connector), pack, path, and enabled (the packs on there).

gateway in the mode, block-at, alert-at, use-pack, and protection results says how the saved change reached the gateway: restarted, live (applied without a restart), not_running (it loads the change when it starts), guardrail_off (takes effect when you run defenseclaw guardrail enable), restart_needed (--no-restart: the running gateway keeps the old setting until you restart it), or restart_failed (the change is saved but the restart failed; exit 1).

Policies

Named security policies (default, strict, permissive, plus any you create) set admission, skill actions, guardrail thresholds, and the firewall defaults. policy list shows only real security policies: the bundled host-firewall template (firewall-deny-default.yaml) is not a named policy, so policy list skips it and policy activate refuses it.

defenseclaw policy list --json | jq -r '.active'
defenseclaw policy show strict --json
defenseclaw policy activate strict              # save + live reload
defenseclaw policy activate strict --no-reload  # save only
defenseclaw policy edit guardrail --block-threshold 3   # active policy blocks HIGH+ now

Credentials

printf '%s\n' "$VT_KEY" | defenseclaw keys set VIRUSTOTAL_API_KEY --value-stdin

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, bare defenseclaw guardrail status, the bare guardrail fail-mode / hilt / block-message reads, 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 X on commands that expose it to narrow the view.
• Mutating guardrail commands — --connector means one connector. guardrail enable / disable / fail-mode / hilt / block-message change 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, --connector scoped. skill, mcp, plugin, and tool policy verbs write broad fallback state by default and one connector's scoped state with --connector X. Config/install verbs such as mcp set, mcp unset, skill install, plugin remove, and codeguard install operate 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, and aibom scan cover configured/active connector sources by default; pass a positional target and --connector X where supported to scope to one.

These list/inventory verbs read across the full active roster:

Audit & alerts

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.

defenseclaw agent usage --refresh --category local_model --detail
defenseclaw agent usage --component Qwen3
defenseclaw agent usage --state seen
defenseclaw agent usage --show-gone

See 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.

Plugin META-* findings are correlations over the atomic plugin findings that remain after the active scan policy is applied. Disabled/suppressed rules, low-confidence matches, documentation, examples, benchmarks, tests, and fixtures cannot become correlation legs. Each emitted correlation carries the atomic rule IDs, locations, and propagated confidence that produced it; its severity never exceeds its strongest atomic input, and its title says pattern (correlated, N signals) because static correlation is not proof that the behavior executed.

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.

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.

TUI

Upgrade

Uninstall / disable

Sandbox

Linux, and Apple-silicon Macs, where sandboxes are OpenShell MicroVMs that work on a copy (see macOS). The sandbox commands run coding agents in NVIDIA OpenShell 0.1 sandboxes. defenseclaw sandbox checks the command line, then hands it unchanged to defenseclaw-gateway sandbox; legacy-cleanup is the one command the Python CLI runs itself. Every command and flag, with an example, is on Sandbox CLI; see also Sandbox.

Enterprise

Commands for administrator-owned enterprise deployments. They are on the Go binary. Run them as root on Linux and macOS, and from an elevated prompt on Windows.

Standalone lifecycle on Linux and macOS

defenseclaw-gateway enterprise linux|macos <action> manages the standalone deployment. Run linux on Linux and macos on macOS; the other one exits 2. Every mutating action is a transaction that rolls back on failure. See Upgrade, repair and remove.

Exit codes: 0 success or no-op, 1 failure (already rolled back), 2 invalid arguments, 75 another lifecycle run holds the lock.

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure --from-package --config /root/defenseclaw-config.yaml --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --purge --json

Lifecycle on Windows

defenseclaw.exe enterprise windows <action> manages the Windows deployment for both profiles. Run it from an elevated prompt. The standalone profile runs its transaction on PowerShell 7, which must be installed.

Exit codes: standalone 0, 1603 failure, 1618 busy, 1639 invalid arguments, and 3010 (reserved). Secure Client: 0 and 1603.

$DefenseClaw = 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe'
& $DefenseClaw enterprise windows status --profile standalone --json
& $DefenseClaw enterprise windows verify --profile standalone --json

Standalone Setup on Windows

DefenseClawSetup-Enterprise-Standalone-x64.exe wraps the standalone lifecycle for MDMs. Its release asset DefenseClawSetup-Enterprise-Standalone-x64.payload-manifest.json lists the payload digests. DefenseClawSetup-Enterprise-x64.exe is the Secure Client Setup. See Install with an MDM.

Property names are case-insensitive, and dashes in them are ignored. Paths must be absolute: Setup refuses relative paths and paths that contain %. The unsigned (hash-pinned) Setup writes its payload trust file itself from its embedded manifest; a signed Setup uses Authenticode trust, optionally pinned with ALLOWEDSIGNERS=. Setup's own argument errors, such as an unknown property, a missing, relative or environment-expanded CONFIG= or MANIFEST= path, /install without CONFIG= and MANIFEST=, or a TIMEOUTSECONDS out of range, exit 1639. A token that is not elevated, or a CONFIG= or MANIFEST= file a non-administrator can change, exits 1603. The Secure Client Setup returns only 0 and 1603.

Machine policy (enterprise policy)

These commands inspect DefenseClaw's entries in vendor machine policy. They never write machine policy; the lifecycle does. See Machine policy.

All three take --json. On this release, set DEFENSECLAW_CONFIG to the managed config path when you run them. Otherwise they read the calling user's ~/.defenseclaw/config.yaml and refuse.

sudo DEFENSECLAW_CONFIG=/etc/defenseclaw/config.yaml /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
sudo DEFENSECLAW_CONFIG=/opt/cisco/defenseclaw/etc/config.yaml /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise policy export --connector claudecode --format plist

Protected credentials (enterprise secret)

Names use lowercase letters, digits, and dashes. Every action takes --json.

Install first, then store the key. See AI Defense key.

Per-user hooks (enterprise hooks)

The guardian and the enumerator services run these commands. Administrators normally need only the lifecycle status and verify, which include the guardian's health.

remove-all and apply-target are hidden internal commands that the lifecycle and the guardian use. The hooks commands read the managed config and the ledger directory from the service environment (DEFENSECLAW_CONFIG, DEFENSECLAW_HOOK_GUARDIAN_AUTH_DIR). To run status or verify yourself, use the same values as the guardian's unit or plist, and pass --manifest on macOS (/opt/cisco/defenseclaw/etc/hook-guardian/targets.yaml).

ACP credentials (enterprise acp)

defenseclaw-gateway enterprise acp enroll|verify|revoke manages the protected ACP credential for one user, client, agent, and profile. See ACP guard.

Discoverability

defenseclaw --help
defenseclaw setup --help
defenseclaw setup guardrail --help
defenseclaw audit --help

Every command tree responds to --help. The CLI prints all flags, defaults, and a one-line description for each.