CLI commands

The defenseclaw and defenseclaw-gateway commands, grouped by what you are trying to do — first run, doctor, setup, guardrail, policy, configuration (config set, get, migrate), asset block and allow lists, scanning, audit, gateway control, upgrade, uninstall.

Commands grouped by task. Tables show the common flags; defenseclaw <command> --help and defenseclaw-gateway <command> --help are the authority for every flag.

Command availability is platform-specific

A registered command or connector alias is not a native Windows support claim. Native Windows supports Amp plus Codex, Claude Code, Cursor, Devin, GitHub Copilot CLI, Antigravity, OpenCode, Hermes and Kiro. OpenClaw and ZeptoClaw are unavailable there. See the connector platform table.

DefenseClaw ships three binaries. Each row below is on the Python CLI unless it names another.

BinaryWhat it is
defenseclawThe operator CLI: init, setup, audit, policy, scans, alerts, doctor.
defenseclaw-gatewayThe Go sidecar: daemon control (start, stop, restart), policy reload, code scanning, audit export, enterprise lifecycle.
defenseclaw-acpThe stdio guard that ACP clients spawn. It checks its runtime contract, then evaluates ACP traffic.

Summary

TaskCommandsSection
Install and first runinit, quickstartFirst run
Check healthdoctor, statusDoctor
Set up agents, providers, scannerssetup ...Setup
Guardrail and policyguardrail, policyGuardrail, Policies
Keys and credentialskeysCredentials
Alerts and auditalerts, auditAudit & alerts
Discovery and scanningagent, skill, mcp, pluginAI discovery, Scanning
Block and allow lists`skillmcp
Gateway daemon`defenseclaw-gateway startstop
Configuration`config getset
Upgrade and uninstallupgrade, uninstallUpgrade, Uninstall
Sandboxessandbox ...Sandbox
Enterprise lifecycleenterprise ..., run by the gateway's full pathEnterprise

config.yaml holds every setting you choose. Every command that changes one (config set, guardrail ..., skill|mcp|plugin|tool block|allow, policy activate, the setup commands, the TUI) goes through the same config writer, which checks the change before it writes. A running gateway applies a valid change itself and shows a new policy generation in defenseclaw status; only the restart-required keys need defenseclaw-gateway restart. Files derived from config.yaml, such as custom-providers.json and the generated hook scripts, are rewritten for you. See Source of truth.

First run

CommandUse it for
defenseclaw initInteractive first-run wizard. On a TTY it pre-selects installed hook connectors and lets you choose observe or action for each. Scripted multi-connector flags are --observe-all and --action-connectors; an explicit --connector keeps the single-connector path. --api-port and --proxy-port set the gateway API and guardrail proxy ports of a new configuration.
defenseclaw quickstartZero-prompt first run for one connector with safe defaults. Pass --connector <name> when more than one is configured or detected. See init and quickstart.
defenseclaw doctorHealth and repair check. See Doctor.
defenseclaw statusGateway state, the Policy line, and one block per active connector. The Policy line names the generation and the first 12 hex characters of the effective policy digest (below). --json adds a policy object. Secure Client has neither the Policy line nor the policy object. A connector whose hook files or registration drifted, or whose agent's own settings turn its hooks off (for example disableAllHooks), shows DEGRADED with the first problem and the step that fixes it.
defenseclaw version [--json] [--no-drift-exit]Versions of the CLI, the gateway binary and the OpenClaw plugin ((not used) unless OpenClaw is an active connector). Exits 1 when the versions differ (not with --json or --no-drift-exit) or a component fails to report.

Doctor

defenseclaw doctor [--json-output | --json] [--passive]
defenseclaw doctor --fix [--dry-run] [--yes] [--fix-id REPAIR_ID]...
FlagWhat it does
--json-output, --jsonPrint schema v2: health in checks and summary, repair attempts in repairs and repair_summary, plus the top-level outcome and exit_code. Repair states are applicable, noop, blocked, manual, requires_confirmation, declined, applied and failed.
--passiveSkip synthetic telemetry, LLM and content-submitting probes.
--fixRun repairs before the health checks, so the summary describes the repaired state. A JSON repair must be a dry-run preview or include --yes.
--fix --dry-runRun the planners only. Always passive; changes no file and restarts nothing.
--fix-id REPAIR_IDRepeatable. Select exactly that repair plus its declared dependencies.
--yesApprove eligible safe and disruptive repairs. It never selects policy or experimental repairs.

Doctor checks configuration, audit and identity state, component and connector compatibility, scanner binaries, gateway health and authentication, the applied policy, derived files, guardrail and scanner services, credentials and observability destinations. It is the command that reaches out: the LLM reachable check sends one request to the configured provider, and on Windows the Codex check starts Codex's own app-server, which reads Codex's cloud requirements from OpenAI. Setting up the Codex connector on Windows runs the same check, so defenseclaw-gateway start and restart, Codex setup, and the installers that start the gateway make those calls too, once per start and before any Codex hook is written. defenseclaw status calls no model vendor.

Rows and fixes for each check are under Read the rows. Preview any repair with defenseclaw doctor --fix --dry-run.

Sample output

defenseclaw doctor checks configuration, audit and identity state, component and connector versions, scanners, the gateway, the policy it applies, credentials and observability destinations. It prints one row per check and exits 1 if a check fails.

defenseclaw doctor

This sample is from a fresh isolated install with Claude Code set up and the gateway not started (paths shortened, rows trimmed with …):

DefenseClaw Doctor
==================

  [PASS] Audit database  -  ~/.defenseclaw/audit.db; SQLite quick_check=ok; required schema present

  -- Connectors --
  [PASS] Connector compatibility: claudecode  -  claudecode matches a supported connector contract; installed=2.1.270; contract=claudecode-hooks-v2; supported=>=2.1.154
  [PASS] Mode [claudecode]  -  observe; fail-mode=closed; provenance=config
  [WARN] Hook contract [claudecode]  -  no hook_contract_lock.json yet - the gateway writes it when it starts: 'defenseclaw-gateway restart' (also starts a stopped gateway)
  …
  -- Scanners --
  [PASS] Scanner: skill-scanner  -  ~/.local/bin/skill-scanner (skill-scanner 2.3.2); cisco-ai-skill-scanner 2.3.2
  [WARN] Scanner settings  -  the skill-scanner LLM judge is off; Add an LLM judge ('defenseclaw setup llm') or the local vLLM option
  …
  -- Services --
  [FAIL] Gateway authentication  -  no gateway token is configured - run 'defenseclaw doctor --fix' to generate and persist one
  [FAIL] Claude Code hooks  -  ~/.claude/settings.json not found
      -> Next step: re-register the hooks: defenseclaw setup claude-code --yes, then restart Claude Code
  …
  -- Summary --
  Health: … passed, … failed, … warnings, … skipped

Read the rows

StatusMeaning
[PASS]The check passed.
[WARN]Works, but something is off or optional is missing. Read the row.
[FAIL]Broken. The line after it, Next step:, says what to run.
[SKIP]Not applicable, or not checked because an earlier check failed (for example while config.yaml is invalid).

Inside an agent's sandbox the config check cannot tell who owns the gateway's folders, so it does not run. The Config validation row then says WARN not run: <reason> (never [PASS]), and config validate and status say the same; run defenseclaw doctor in a normal terminal to check config.yaml. When config.yaml cannot be loaded at all, the Config load row keeps the loader's reason.

Rows are grouped by the section headers: the first group (configuration, audit database, device identity, private files), Connectors (versions, mode, hook files, rule pack per agent, tagged [<connector>]), Scanners, Services (gateway, authentication, policy, hooks, human approval, proxy), Credentials, Observability, Webhooks, Sandbox and Security Overrides.

Options

CommandWhat it does
defenseclaw doctor --passiveSkip checks that send test traffic, call an LLM or submit content.
defenseclaw doctor --jsonMachine-readable schema v2. Health is in checks and summary; repairs in repairs and repair_summary; the top level has outcome and exit_code. Also --json-output.
defenseclaw doctor --fix --dry-runList what --fix would repair. Changes nothing and is always passive.
defenseclaw doctor --fix --yesApply every safe and disruptive repair that applies. A repair runs before the checks, so the summary shows the repaired state.
defenseclaw doctor --fix --fix-id IDApply one repair and its declared dependencies. Repeatable.

The LLM reachable check sends one request to your provider. defenseclaw status reads only local state and the local gateway.

--yes never selects policy-changing or experimental repairs. Recreating the device key always asks first; do not add --yes:

defenseclaw doctor --fix --fix-id doctor.identity.device-key.initialize

Policy generation and digest

Not available on Secure Client.

Each time the gateway applies config.yaml and the policy assets it names by digest, it builds a policy snapshot and swaps it in. Each snapshot has an effective policy digest: a SHA-256 over the canonical configuration, with secrets dropped, plus the asset digests. Plain defenseclaw status prints the applied config generation and the digest:

  Sidecar:      running (PID 709868, up <1m, API http://127.0.0.1:19347)
  Policy:       config generation 2, sha256:22fa11f6a549

The Policy line in plain defenseclaw status shows policy.config_generation, the same applied counter as the TUI footer. The counter is kept in config.generation.json with the file's SHA-256, the actor (cli:alice, tui:alice, hand-edit:alice) and the reason. config set prints the generation it saved; on a per-user install the gateway also records an applied hand edit as the next config generation. The separate policy.generation field is the gateway-local policy-build counter and restarts at 1 with the gateway. defenseclaw status --json carries effective_digest, generation, config_generation and last_reload_error in its policy object. If the gateway rejects a change it keeps the previous applied config generation and says so:

  Policy:       config generation 20, sha256:f61a485cfcbf; the last change was rejected (see defenseclaw doctor)

Compare the running digest with what is on disk:

defenseclaw-gateway policy digest
Effective policy: sha256:8b19ede823440a16171f0d77b7560c47c07c96ce48ebc1b626229955d2aa9131
Config generation: 42
  builtin                          sha256:31191aec6bcc38a8d63e718a5a6cf9c3bce38229b275f0cf408239901350c6e1
  config                           sha256:cb9b627c63095bbc907dcd858525b648546e4c00120ece557938438d9292d4fb
  guardrail_policy                 sha256:21849ef9fb0e830d2897fe206ec1a6fcba18979714d5ed491cf41830b76aa364
  providers                        sha256:669121342bade4df6cfdff05e99f579eb6d81a3f8c6a936b4578572c7cdc8757
  rego                             sha256:1394e701de498838fa07251f7d5d3c858ed6ce44dcc164536fd13dc58d2a38b3
  rule_pack:global                 sha256:901eca4d7682a51a6d34d123efed366b629b59252180f88a3e1d656dbfa6b34f

--json prints the same as effective_digest, components, config_generation and config_generation_recorded. The gateway also stamps the digest on /health, /status and decision events (defenseclaw.policy.effective_digest, defenseclaw.policy.generation).

Doctor rows for policy, migration and derived files

RowStatusWhat it says and what to do
PolicyPASSgeneration N, digest sha256:... (applied by the gateway). The gateway applies what config.yaml and its assets compute to.
PolicyFAILEither the last change was rejected (... is still enforcing: the last change was rejected (<reason>): fix what the reason names, and the gateway applies it once it builds), or the gateway applies a different digest than the files compute to (run defenseclaw-gateway restart).
PolicyWARNconfig.yaml was edited outside the DefenseClaw writer: the edit is not yet in config.generation.json. On a per-user install the running gateway records the hand edit itself (actor hand-edit:<user>) and the row clears. Make later changes with defenseclaw config set, the TUI or defenseclaw setup.
Config validationFAILconfig.yaml is invalid; the line names the field. A running gateway keeps the config it started with.
Retired policy dataWARNA leftover policies/rego/data.json (or policies/data.json) is ignored since config_version 9, because admission and thresholds live in config.yaml. Review defenseclaw config get admission, then remove the file.
Config migrationPASS or WARNmigrated to 9 on <date>: N value(s) moved, N conflict(s); details in .../migration-v9.json. Shows until you run defenseclaw-gateway config migrate --ack. WARN when the migration recorded conflicts. With no migration record, defenseclaw config migrate --ack says there is nothing to acknowledge and exits 0.
Custom-provider overlayFAILcustom-providers.json was edited by hand or no longer matches llm_providers. The gateway ignores those edits. defenseclaw doctor --fix rewrites it.
Hook runtime filesFAILA generated hook script was edited or replaced. defenseclaw doctor --fix re-renders it.
Orphaned hook entries [<connector>]FAIL or WARNEntries remain for a connector that is no longer configured. A missing script or credential fails the check; an existing target warns. Run defenseclaw setup remove CONNECTOR.
Native OTLP credentialsWARNAn agent can keep an old credential after an upgrade, rollback or token rotation. Restart that agent and its background server, then run doctor again.
Claude Code hooks freshness, Codex hooks freshnessWARNstale generated script (...): a hook script is from an older build, or bakes a different fail mode. The line names the command that regenerates it. A script edited by hand or copied from another build warns a generated script is not the one setup rendered (...) instead, next to the Hook runtime files FAIL; defenseclaw doctor --fix renders it again.

Real lines (paths shortened). A healthy gateway:

  [PASS] Policy  -  generation 2, digest sha256:22fa11f6a549 (applied by the gateway)

A hand-edited custom-providers.json:

  [FAIL] Custom-provider overlay  -  /home/alice/.defenseclaw/custom-providers.json was edited by hand; the gateway ignores those edits

A rejected change, here a custom rule pack whose files changed after it was pinned. The writer refuses such a change up front. The gateway rejects it when someone edits the file by hand:

  [FAIL] Policy  -  generation 20, digest sha256:f61a485cfcbf is still enforcing: the last change was rejected (config reload rule pack preflight: global rule pack "badpack": digest sha256:47c1... does not match guardrail.custom_packs.badpack.digest)
      -> Next step: Fix the change the error names in config.yaml or the policy asset; the gateway applies it once it builds

After a migration that moved values:

  [PASS] Config migration  -  migrated to 9 on 2026-10-06: 21 value(s) moved, 0 conflict(s); details in /home/alice/.defenseclaw/migration-v9.json

Cowork row in status and doctor

On a per-user install, defenseclaw status and defenseclaw doctor show a Cowork row when Claude Desktop is installed or defenseclaw setup cowork built a plugin. Neither shows it on a managed computer, where machine policy covers Cowork and the cowork line of the managed status and verify takes its place (see Configured versus covered). The reason codes and what to do about each are in Check it.

doctor reports it as the check doctor.cowork, labelled Cowork. The status is pass when Cowork is protected and warn otherwise. In doctor --json the check carries the reason_code and a remediation with the step.

status --json has a cowork object only when the row is shown:

FieldMeaning
protectedtrue when a Cowork hook call reached this account's gateway after the current plugin build
detailThe sentence the text row prints
stepWhat to run or do next. An empty string when protected
reason_codeWhy Cowork is not protected, such as cowork_plugin_not_built or cowork_no_events. An empty string when protected
last_event_atThe time of the last Cowork event as an ISO 8601 string, or null
plugin_versionThe plugin version setup built, or null
plugin_zipThe path of the plugin zip, or null

Observability rows

RowStatusWhat to do
Codex OTel environmentPASS or FAILCodex's otel.environment in config.toml must match DefenseClaw's environment. FAIL names the mismatch, or a config.toml it cannot find or read.
Codex OTel ownershipWARNA config.toml value is nested too deeply to check for a DefenseClaw credential, so DefenseClaw kept it. Remove it if it is a DefenseClaw token.
Codex OTel runtimePASS or SKIPCompares with the gateway's authenticated telemetry status; SKIP while that status is not available (gateway stopped or no token).
Connector OTLP: CONNECTORPASS, WARN or FAILOTLP a connector exports to the gateway; not configured when none does.
Native OTLP credentialsWARNThe gateway refused native OTLP attempts that carried an old credential, usually a Codex daemon after an upgrade. Run codex app-server daemon restart; the row clears 24 hours after the last refused attempt.

defenseclaw status prints the config generation the gateway applied (the number config set prints, from config.generation.json) and the policy digest. Compare it with what the files compute to: defenseclaw-gateway policy digest.

What doctor --fix regenerates

Doctor never edits config.yaml unless a repair says so.

Repair IDRiskWhat it does
doctor.providers.overlay.regeneratesafeRewrites custom-providers.json from llm_providers.
doctor.connector.hook-scripts.restore-modesafeRestores the owner execute bit on sealed hook scripts. It does not re-render them.
doctor.connector.hook-scripts.regeneratedisruptiveRe-renders a connector's hook scripts that no longer match the sealed digest and seals the new one. On a managed host enterprise <os> repair does this.
doctor.state.audit-db.reopendisruptiveRestarts the gateway when audit.db was deleted or replaced while it ran.
doctor.state.audit-db.initializesafeCreates an empty audit.db only when none exists and the gateway is stopped. It never replaces or erases an existing file.
doctor.state.private-files.protectsafeMakes device.key, its provenance files and audit.db readable by your account only (mode 0600, or a private Windows DACL). An exposed .env goes through gateway token rotation instead.
doctor.install.stale-lock.clearsafeRemoves a stale .install.lock: one whose installer is gone. The installer is gone when the lock's pid names no process (or one that has exited but is not yet reaped), or a different process than the one that wrote the lock. The lock records the installer's process start as the system keeps it, so a clock change does not affect the check. A lock written by 1.0.4 or earlier has no such record: it is stale when its pid now names a process that started more than 2 seconds after the lock's pid file was written. A running installer keeps its lock for as long as it runs. A lock with no valid pid, or one doctor cannot read, holds; run the installer again to clear it. Hooks treat a stale lock as no lock. When an interrupted-install record (previous.new, .repair, .rollback-hold, .lifecycle-txn.json) sits beside a lock whose installer is gone, doctor warns that hooks hold no tool call for it (the strict tier blocks them, and no hook starts the gateway) and leaves the lock for the installer to finish or undo. Doctor removes the lock only if it is still the same folder with the same owner as when it checked; a lock an installer took over in the meantime stays in place. Doctor and installers take a stale lock over one at a time: each first leaves a claim file (claim-<pid>-...) in the lock, and one that finds another live claim leaves the lock alone.
doctor.identity.device-key.initializeexperimentalMints a new device.key when it is missing. Run it without --yes; earlier pairings cannot be recovered. Orphaned provenance files are moved aside as *.orphaned-<time>.
doctor.connector.proxy-lock.refreshdisruptiveDrops the OpenClaw or ZeptoClaw entry of hook_contract_lock.json when it names another agent version, and restarts the gateway to record the installed one.
doctor.acp.guard.repinsafeRe-pins the upgraded ACP guard in the editor entries DefenseClaw wrote.
doctor.gateway.token.ensuredisruptiveGenerates a missing local gateway token, or restarts a gateway holding a stale one. It never overwrites a custom token_env or prints a token.
doctor.gateway.token-env.canonicalizesafeSaves the canonical gateway token provider in config.yaml.
doctor.policy.plugin-registry.clear-dead-endpolicyChanges explicit plugin admission policy in config.yaml. Select it by ID.

Version findings are reported, not repaired: doctor.connector.compatibility.review and doctor.component.compatibility.review name the range or the upgrade to run.

To rotate the gateway token on purpose, run defenseclaw setup rotate-token --yes. Repeated export failures to one observability destination pause it; fix it and reload, or run defenseclaw setup observability disable NAME.

Doctor repair safety

  • Gateway token. Doctor may generate a missing token, start a stopped gateway, or restart one whose token is stale. It never overwrites a custom token_env and never prints a token. To rotate on purpose: defenseclaw setup rotate-token --yes, then restart each agent.
  • An exposed .env. If another local user could read it, doctor rotates the gateway token instead of only tightening permissions. Rotate the other credentials in the file yourself.
  • The gateway binary. Doctor checks that only an administrator or your account can change defenseclaw-gateway and its directory. It refuses a file that fails the check, for example with chmod go-w <file> as the fix.
  • A missing audit database. defenseclaw doctor --fix --dry-run --fix-id doctor.state.audit-db.initialize previews it. Doctor creates a database only when none exists and the gateway is not running, and never erases an existing one.
  • Observability. Repeated export failures pause one destination (a circuit breaker); local history and other destinations keep working. Fix and reload the destination, or run defenseclaw setup observability disable NAME.

Install and upgrade failures: Troubleshooting. Agents: Troubleshoot DefenseClaw.

Setup

Hook setup aliases (setup codex, setup claude-code and the rest) add or reconfigure one connector. With another hook connector already active, choose Add to join the roster or Replace to return to one connector. Proxy connectors (openclaw, zeptoclaw) own the traffic plane and do not join the hook-connector roster.

CommandUse it for
defenseclaw setup guardrailThe central setup command. See setup guardrail.
defenseclaw setup remove CONNECTOR [--force] [--yes]Remove one connector from the active roster; the gateway restart tears down its hooks. If the connector is already absent, the command removes DefenseClaw hook entries it left in the agent settings. Removing the last configured connector needs --force. To take DefenseClaw off the machine, use defenseclaw uninstall. setup remove claudecode does not remove the Cowork plugin from your Claude account; see Remove the Cowork plugin. With --no-restart, a running gateway removes the connector's hooks when it reloads the config (within seconds) and a stopped one removes them when it next starts; if the removed connector was the primary one, its hooks stay until the gateway restarts.
defenseclaw setup gateway [--api-port N] [--host H] [--port N] [--remote] [--non-interactive]Set the sidecar REST API port (--api-port) and the upstream agent gateway connection: host, WebSocket port, and auth token (--remote; the token can come from AWS SSM Parameter Store). Runs connectivity checks afterward unless --no-verify. Port values take 1-65535; anything else is refused when the command parses.
defenseclaw setup rotate-token [--yes]Rotate the gateway token and every connector-scoped hook credential in one transaction, then refresh the hooks and verify the restarted gateway. A failure after the gateway stops restores the previous credentials. Rotation is always global; --connector does not narrow it.
defenseclaw setup skill-scanner / setup mcp-scannerConfigure the skill and MCP scanners: analyzers, the LLM judge, optional VirusTotal, AI Defense and OSV lookups, and the scan policy. They write scanners.skill_scanner.* or scanners.mcp_scanner.* (and the shared llm: block) in config.yaml, then restart a running gateway, as most setup subcommands do. --non-interactive takes every choice from flags; the flags are below. See Scanners.
defenseclaw setup registryInteractive wizard that registers a skill or MCP catalog; the same as defenseclaw registry wizard. See Registries.
defenseclaw setup migrate-llm [--dry-run] [--no-backup]Rewrite a config.yaml that still carries pre-v5 inspect_llm, default_llm_* or guardrail LLM fields into the unified llm: block, writing config.yaml.bak first unless --no-backup. On a current config it prints Config already in v5 shape — nothing to migrate.
defenseclaw setup routing --enable|--disable|--statusConfigure or inspect semantic model routing for proxy-mode OpenAI Chat Completions traffic. Managed mode requires Docker; all config changes activate on gateway restart. See Semantic routing.
defenseclaw setup llm [--show] [--non-interactive] [--provider P] [--model M] [--api-key-env NAME]Write the unified or role-scoped LLM block (--role unified|agent|judge) in config.yaml; the key itself goes to ~/.defenseclaw/.env. --show prints the resolved values and changes nothing. Supports SaaS providers and regional Bedrock / Vertex AI / Azure OpenAI via dedicated --bedrock-*, --vertex-*, --azure-* flags, plus --instance-name to bind a custom provider from llm_providers (use --provider custom) and --inherit-from to seed from a sibling component. --ping / --no-ping sends (or skips) a one-shot reachability probe after saving. See LLM providers.
defenseclaw setup provider add|list|show|removeManage llm_providers.custom entries that route LLM traffic through internal or self-hosted endpoints. custom-providers.json is derived from them; never edit it. add writes the entry and asks a running gateway to reload its provider registry (--no-reload skips); omit --name for the wizard. list prints the live registry. add flags are below.
defenseclaw setup claude-codeHook setup alias for Claude Code. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup codexHook setup alias for Codex. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup cursorUser-hook alias for Cursor. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). --mode action uses event-native deny. Both modes set failClosed: true for hook-process failure outside Secure Client. Native human approval is not enabled.
defenseclaw setup devinNative Devin CLI hook alias. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). --mode action can block only on the four documented block-capable events.
defenseclaw setup copilotHook setup alias for GitHub Copilot CLI. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. If an earlier managed install left defenseclaw@defenseclaw enabled in Copilot's machine managed-settings file, setup copilot and setup remove copilot print a warning that names the file and asks an administrator to delete the entry; a standard user cannot remove it.
defenseclaw setup hermesHook setup alias for Hermes. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup antigravityHook setup alias for Antigravity (agy). Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. Native ask and deny are documented only for PreToolUse; no permission-bypass override is claimed.
defenseclaw setup opencodeHook setup alias for OpenCode; writes the auto-loaded bridge plugin. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup acpFind ACP agents an editor is launching unguarded and route them through defenseclaw-acp. Reuses the per-pair acp setup transaction and points the operator's existing entry at the guard, so no unmediated duplicate is left behind. Defaults to observe; --activate selects action. Alias of defenseclaw acp adopt.
defenseclaw setup kiroNative hook alias for Kiro IDE and Kiro CLI. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. The .kiro/hooks surface (Kiro IDE and kiro-cli --v3) vetoes PreToolUse, and UserPromptSubmit in Kiro IDE (kiro-cli 2.24.1 --v3 still sends a blocked prompt to the model); the CLI 2.x agent config vetoes PreToolUse only. ACP is optional and configured separately with defenseclaw acp setup --agent kiro.
defenseclaw setup ampDirect-to-upstream system-policy setup for Amp; writes the TypeScript plugin. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). 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 cowork [--yes|--non-interactive] [--open-claude|--no-open-claude] [--wait|--no-wait] [--timeout SECONDS]Per-user Claude Cowork route. Builds the DefenseClaw plugin zip for your Claude account, shows the upload steps and waits for the first Cowork event. Sets up the Claude Code connector first if it is off. Cowork is not a connector. Exits 3 on a managed computer. See Claude Cowork.
defenseclaw setup openclawFull guardrail alias for OpenClaw (proxy connector); unsupported in the native Windows release.
defenseclaw setup zeptoclawFull guardrail alias for ZeptoClaw (proxy connector); unsupported in the native Windows release.
defenseclaw setup local-observability up|down|status|logs|url|env|resetBring up the bundled Prom/Loki/Tempo/Grafana stack, tear it down, show its readiness, tail its logs (--service, --follow), print the Grafana and backend URLs or the environment that points a gateway at it, or reset it (stop it and delete its stored metrics, logs, and traces). up --password requires the managed Grafana credential; up --no-password explicitly selects anonymous read-only (Viewer) access on managed loopback; anonymous access is never Admin. New stacks default to password and previously used anonymous stacks keep anonymous access, read-only. down keeps the data volumes; down --disable-config also turns off the local-observability destination.
defenseclaw setup galileo [status|test|enable|disable|remove]Configure and verify Galileo Cloud or self-hosted OTLP traces.
defenseclaw setup splunkConfigure local Splunk in Docker, Splunk Enterprise HEC, or Splunk Observability Cloud.
defenseclaw setup webhook add|list|show|enable|disable|remove|testConfigure Slack, PagerDuty, Webex, or generic notifier webhooks (chat and incident routing). add <type> creates or updates one (--non-interactive with --url, --secret-env, --min-severity, --events; --dry-run previews); test NAME sends a synthetic event. Secrets are referenced by environment name and never printed.
defenseclaw setup splunk dashboards plan|apply|destroyCreate, update, or remove the DefenseClaw dashboards (and, with --with-detectors, detectors) in Splunk Observability Cloud through Terraform. plan shows the changes first.
defenseclaw setup notifications [on|off|status]Turn desktop notifications for blocks and pending approvals on or off. Bare, it asks once. setup notifications-set <category> <value> toggles one category or source. Notifications are informational; they never approve or deny anything.
defenseclaw setup observability add|list|enable|disable|remove|testManage 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. In the TUI: TUI → 0 Setup → Guardrail & scanning → Redaction. In the macOS app: Logs → Redaction policy….
defenseclaw observability planPrint the masked effective v8 graph: generated local SQLite policy, collection, destination capabilities, routes, profiles, retention, and warnings.
defenseclaw observability destination test NAME [--write-probe] [--timeout S]Test one destination's DNS, connection, TLS, and protocol without ordinary collection or fan-out. --write-probe also sends one marked, content-free probe where the destination supports it; OTLP supports the handshake only and refuses --write-probe. A local or pull destination (jsonl, sqlite, console, prometheus) has nothing to reach: the test says SKIPPED and exits 0, as does defenseclaw setup observability test NAME.

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.

Remove every configurable redaction override:

defenseclaw setup redaction remove-all --dry-run
defenseclaw setup redaction remove-all --yes

Profile none permits governed content without redaction

remove-all selects profile none for configurable log and trace projections. It can expose governed content to configured destinations; confirm each has an approved trust boundary before using --yes. It never weakens the release-owned managed enterprise destination. See Redaction.

CommandUse it for
defenseclaw setup trusted-paths list|add|removeManage the directories trusted for connector-binary version probing (action-mode setups refuse binaries outside this allow-list). list shows built-in defaults (the folders setup admits, with discovery default marking any that only passive discovery uses) plus operator additions, with source and status; add validates the directory (world-writable / relative paths refused unless --force) and writes it to ai_discovery.trusted_binary_prefixes in ~/.defenseclaw/config.yaml; remove only touches operator-added entries (in config.yaml, or an older entry in ~/.defenseclaw/.env). 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.

setup provider add flags

add accepts --name, --base-url and --domain (repeatable; optional with --base-url, but without a domain that covers the base_url host the gateway cannot match inbound URLs back to the entry, and defenseclaw doctor warns), --base-provider-type, --env-key, --allowed-request, --available-model, --request-path-override, --profile-id, --ollama-port, the TLS options --ca-cert-file and --insecure-skip-verify, and --no-reload (save without asking the running gateway to reload its registry). remove --name NAME takes --no-reload too. Provider-specific flags are rejected when they don't match --base-provider-type:

ProviderFlags
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)
defenseclaw setup provider add --name acme-llm --base-url https://llm.acme.example.com:8443 \
  --domain llm.acme.example.com --env-key ACME_LLM_KEY --base-provider-type openai
  ✓ provider 'acme-llm' written to config.yaml llm_providers (derived /home/alice/.defenseclaw/custom-providers.json)
  domains: llm.acme.example.com
  env_keys: ACME_LLM_KEY
  base_provider_type: openai
  base_url: https://llm.acme.example.com:8443
  ✓ sidecar reloaded provider registry; disk and live state match.

setup skill-scanner and setup mcp-scanner flags

Both commands prompt for each choice unless you pass --non-interactive. Every on/off option is a --x / --no-x pair; --verify / --no-verify runs (or skips) connectivity checks after saving and defaults to on.

CommandFlagsWrites
setup skill-scanner--use-llm, --use-behavioral, --enable-meta, --use-trigger, --use-virustotal, --use-aidefense, --use-osv (each with a --no- form)scanners.skill_scanner.use_* and enable_meta; VirusTotal, AI Defense and OSV also need their keys (defenseclaw keys set)
--llm-provider P, --llm-model M, --llm-base-url URL, --llm-consensus-runs NThe judge in the shared top-level llm: block, and scanners.skill_scanner.llm_consensus_runs. --llm-base-url applies to openai-compatible and vllm judges
--policy strict|balanced|permissive|low-noise|quietscanners.skill_scanner.policy. quiet is the recommended preset
--fail-on-severity and --review-queue-min, each info|low|medium|high|criticalThe scanner gate: findings at or above the first block, findings from the second up to the gate go to review. Recommended: HIGH and MEDIUM
--lenient / --no-lenientTolerate malformed skills, or fail them
setup mcp-scanner--analyzers yara,api,llm,behavioral,readinessscanners.mcp_scanner.analyzers. auto stores an empty list, and the scanner then picks YARA plus a ready LLM
--llm-provider P, --llm-model MThe judge in the shared llm: block
--api-endpoint URL, --api-key-env NAME, --api-timeout-ms Ncisco_ai_defense.endpoint, .api_key_env and .timeout_ms for the api analyzer
--scan-prompts, --scan-resources, --scan-instructions (each with a --no- form)What else the scan covers: MCP prompts, resources and server instructions
defenseclaw setup skill-scanner --non-interactive --policy quiet \
  --fail-on-severity high --review-queue-min medium --no-verify
defenseclaw setup mcp-scanner --non-interactive --analyzers yara --scan-prompts --no-verify
  Saved to ~/.defenseclaw/config.yaml

    scanners.skill_scanner.policy:           quiet
    scanners.skill_scanner.fail_on_severity: HIGH
    scanners.skill_scanner.review_queue_min: MEDIUM
    scanners.skill_scanner.lenient:          true

--llm-provider accepts any provider setup llm does, plus openai-compatible. For what the analyzers, policies and the gate mean, see Skill scanner and MCP scanner.

Change one setting without a wizard

These commands edit one thing in config.yaml, check the result before they write, and print the new config generation. The gateway applies the change itself, except for the restart-required keys.

To changeRun
Any keydefenseclaw config set KEY VALUE; config unset KEY returns it to the default.
What blocks and what alertsdefenseclaw guardrail block-at LEVEL and alert-at LEVEL, with --connector X for one connector (Thresholds).
The rule pack, one rule, a suppressiondefenseclaw guardrail use-pack, guardrail rule enable|disable|severity and guardrail suppress add|remove (Rules).
A skill, MCP server, plugin or tool block or allow listdefenseclaw skill|mcp|plugin|tool block|allow|unblock NAME (Admission).
A custom LLM endpointdefenseclaw setup provider add, which writes llm_providers. custom-providers.json is derived from it.
The LLM that judges and scansdefenseclaw setup llm.
Scanner analyzers and policydefenseclaw setup skill-scanner and setup mcp-scanner.
A version 8 file to version 9defenseclaw migrate or defenseclaw config migrate (Migrate to version 9).

On a managed standalone device these are refused with exit 3; see Managed devices.

Interactive and scripted forms

CommandInteractiveScriptedNotes
initOn a TTY--non-interactive --yes plus option flags--fail-mode, --observe-all and --action-connectors cover what it asks.
quickstartNoAlwaysZero-prompt by design; use init for the wizard.
setup guardrailDefault--non-interactive plus flagsMissing flags fall back to wizard defaults. Hook fail mode and judge fallback models have no flag here.
setup <connector>YesFlags plus --yesWith other connectors configured the default, also under --yes, is to add; --replace switches. With --mode, a TTY run does not ask for the mode again.
setup routingNo--enable, --disable, --statusNeeds Docker. Proxy-mode OpenAI Chat Completions traffic only.
keys setHidden prompt without a value--value-stdin (or --value, visible in ps)See Keys.
keys fill-missingYes--yes skips the opening confirmationPrompts for every required key that is unset.
keys list, keys checkNoAlwayskeys check exits non-zero when a required key is missing.
keys removeAsks to confirm--yes
setup webhook add <type>Default--non-interactive plus flagsThe type is positional; URL and secret env are prompt-or-flag.
setup webhook test <name>NoAlways--dry-run formats without delivering.
registry add <id>Default--non-interactive plus flagsregistry wizard is the first-run add-and-sync flow.
registry sync, entries, approve, rejectNoFlags onlyFor cron and scripts.
setup splunkWhen no mode flag is given--non-interactive with --logs, --enterprise or --o11yThe HEC token comes from --hec-token or DEFENSECLAW_SETUP_SPLUNK_HEC_TOKEN; the variable keeps it out of ps.
setup local-observabilityNoSubcommandsup is the default; down keeps data; reset deletes it.
setup redactionBare commandSubcommands plus flagsThe simple flow leads into Show advanced settings? for buckets, profiles, destinations and routes.
setup skill-scanner, setup mcp-scannerYes--non-interactive plus flags
config set, config unsetNoAlways--json for list and object values; --expect-sha256 refuses a change when config.yaml moved.
skill|mcp|plugin|tool block, allow, unblockNoAlwaysWrite asset_policy; no gateway call needed.
migrate, config migrateNoAlways--check or --dry-run previews; config migrate --ack marks the record as read.
sandbox setupDefault--non-interactive, or --yes for every defaultOne-time OpenShell setup on Linux or an Apple-silicon Mac.
doctorOnly with --fix--fix --yesA plain run is read-only and never prompts.
alertsNo--limit, --connector, --show <n>, --json; acknowledge and dismissA snapshot, not a live tail.
tuiFull-screenNoneInteractive only.
defenseclaw-gatewayNo--host, --portBare, it runs the foreground daemon; start, stop and restart manage the background one. Most setup commands restart a running gateway (setup guardrail takes --restart and --no-restart).

For what setup writes and where, see On-disk layout.

ACP guard

Editor agents that speak the Agent Client Protocol (Zed, JetBrains) are guarded by defenseclaw-acp. See ACP guard.

CommandUse it for
defenseclaw acp detect [--json-output]Report every known ACP client and classify each agent server as guarded, adoptable, client-registry (unmediated but not wrappable), or foreign. Read-only.
defenseclaw acp adopt [--client X] [--activate] [--yes]Adopt the agents detect found.
defenseclaw acp catalogShow the pinned ACP schema and built-in client/agent inventory.
defenseclaw acp setup --client zed|jetbrains --agent <name> [--activate]Install or reconfigure a managed guarded entry. Defaults to observe mode.
defenseclaw acp statusShow the ACP posture and configured bindings (--json for the machine-readable document).
defenseclaw acp remove --client <client> --agent <agent>Remove only the DefenseClaw-owned entry.
defenseclaw acp verify [--client X] [--agent Y]Fail when a managed editor entry or the guarded executable's digest has drifted. With no --client/--agent, every configured binding is checked.
defenseclaw acp refresh [--from-sha256 <digest>]Re-pin the upgraded defenseclaw-acp guard in configured editor entries (the installer runs it after an upgrade). A changed agent binary or editor entry still needs acp setup.

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, enable, disable, fail-mode, hilt and block-message accept the active name and use their global path; another name is refused. mode, block-at, alert-at, use-pack and protection accept the active name and write its override block. All of these are on the Python defenseclaw CLI.

CommandUse 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 mode observe|action [--connector X] [--clear] [--no-restart] [--json]Switch between observe (logs policy findings without enforcing them) and action (enforce). Hook fail mode and proxy availability still apply. Sets guardrail.mode, or with --connector X only guardrail.connectors.X.mode; --clear --connector X removes X's override. The running gateway applies it on its next reload. A changed hook fail mode is re-rendered into the hook scripts of Claude Code, Codex, Amp and OpenCode in place; other hook connectors restart the gateway (--no-restart skips; a stopped gateway is never started). --json prints {"version": 1, "ok", "scope", "mode", "previous", "mode_source", "changed", "not_covered", "gateway", "message"}.
defenseclaw guardrail block-at LEVEL [--connector X] [--json]Set the lowest severity the guardrail blocks at: CRITICAL, HIGH, MEDIUM, LOW (any case) or inherit to clear. Writes guardrail.block_at, or with --connector X only guardrail.connectors.X.block_at. A connector's own level wins over the global one, which wins over the rule pack's (strict blocks MEDIUM+, default and permissive CRITICAL). It applies in action mode to prompts, completions, tool calls and tool responses, on hooks and through the proxy; policy edit guardrail --block-threshold sets the same key. See Tool-call levels. Refused on a managed standalone device (exit 3).
defenseclaw guardrail alert-at LEVEL [--connector X] [--json]The same for the lowest severity that raises an alert (guardrail.alert_at, pack levels: strict LOW+, default MEDIUM+, permissive HIGH+). Anything that blocks also alerts, so an alert level above the block level alerts from the block level.
defenseclaw guardrail disable [--connector X]Kill switch. Global disables everything; --connector X drops only that connector from the active set and removes its hooks.
defenseclaw guardrail fail-mode [--connector X]Show each active connector's gateway-outage mode. On a per-user install open or closed saves your choice, which wins over the policy tier (except OpenClaw under the strict policy and ZeptoClaw model requests, which stay closed despite a saved open); with no saved value the tier decides (default and permissive run the call with a warning, strict blocks it; select strict with guardrail use-pack strict). An administrator sets an outage-only open in managed config. See 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. The running gateway applies a change without a restart; on a Secure Client computer the command restarts it (--no-restart to skip).
defenseclaw guardrail block-message ["<text>"] [--clear] [--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. --clear --connector X removes that connector's override so it inherits the global message, or the built-in default when the global value is empty. Unscoped --clear also clears active connector overrides, returning the active roster to the built-in default. Do not pass text and --clear together.
defenseclaw guardrail list-packs [--json]Read-only. Lists the built-in rule-pack presets, custom packs found under ~/.defenseclaw/policies/guardrail/ or configured anywhere, and the pack each active connector enforces (per-connector override > global pack > built-in default). --json prints {"version": 1, "global": {...}, "connectors": [...], "packs": [...]}.
defenseclaw guardrail use-pack PACK [--connector X] [--no-validate] [--repin [--yes]] [--json]Switch rule packs. PACK is a preset (default, strict, permissive), a guardrail.custom_packs key, a pack name under ~/.defenseclaw/policies/guardrail/, or a directory. It is written as guardrail.rule_pack; a custom directory is also pinned as guardrail.custom_packs.NAME with its validated digest, so an edited pack is refused until --repin pins it again (it shows the pinned and the new digest, names the other scopes that share the pin, lists every config.yaml edit, and asks; if config.yaml changed meanwhile it saves nothing and says to run it again; --yes for scripts, which --json needs). An invalid pack changes nothing; --no-validate skips validating a built-in pack. Without --connector, every connector uses PACK and per-connector packs are removed. --json prints {"version": 1, "ok", "scope", "connector", "pack", "path", "cleared_overrides", "validation", "gateway", "message"}.
defenseclaw guardrail use-pack --clear --connector XRemove X's rule-pack override so it uses the global pack again.
defenseclaw guardrail protection list [--json]Read-only. Lists the opt-in protection packs (five selectable, one staged) and which scope (the global pack or an active connector) has which on. See Opt-in protection packs.
defenseclaw guardrail protection enable NAME [--connector X] [--profile P] [--json]Turn an opt-in protection pack on for a scope: adds NAME to guardrail[.profiles.P][.connectors.C].rules.protections, which the gateway layers onto the scope's rule pack on its next reload. Staged and unknown packs are refused (exit 1). The gateway composes the pack in memory on its next reload; nothing is restarted.
defenseclaw guardrail protection disable NAME [--connector X] [--profile P] [--json]Remove NAME from that scope's rules.protections. If a wider scope enables it, the command refuses with exit 1; disable it at that wider scope.
defenseclaw guardrail rule enable|disable RULE_ID [--connector X] [--profile P] [--json]Turn one rule on or off for a scope (guardrail.rules.enable / disable). An ID the scope's rule pack does not have is refused by the gateway when it reloads, and the previous configuration keeps running.
defenseclaw guardrail rule severity RULE_ID critical|high|medium|low|default [--connector X] [--profile P] [--json]Change one rule's severity for a scope (guardrail.rules.severity_overrides); default removes the override.
defenseclaw guardrail suppress add SUPPRESSION_ID --finding REGEX --reason TEXT [--entity REGEX] [--connector X] [--profile P] [--json] / suppress remove SUPPRESSION_IDAdd or remove a finding suppression (guardrail.rules.suppressions). The reason is recorded in config.yaml.
defenseclaw guardrail allow-private-upstream [HOST|IP ...] [--remove] [--no-restart]Let the guardrail proxy reach an LLM endpoint on a private address, such as an AWS PrivateLink (VPC interface) endpoint for Bedrock, whose hostname resolves to private IPs. A hostname is resolved now and its private addresses are stored in guardrail.allow_private_upstreams; run it again if the endpoint's addresses change. Run bare it lists the entries. Loopback, link-local and cloud metadata addresses are never allowed. A running gateway is restarted so the proxy uses the change at once (--no-restart to skip).
defenseclaw guardrail validate-pack PATH [--json]Validate a rule pack offline with the gateway's own validator. Exit 1 means invalid, 2 means the validator is unavailable.
defenseclaw guardrail profile list [--json]Read-only. Lists the identity-based guardrail profiles, their ordered assignments and the default profile. See Guardrail profiles.
defenseclaw guardrail profile show NAME [--json]Read-only. One profile's settings and the assignments that select it.
defenseclaw guardrail profile explain [--user U] [--connector C] [--agent agt-...] [--json]Ask the running gateway which profile a subject resolves to and why: the profile, the match reason (and matched group), the digest and the effective mode, levels, HILT and rule pack. --user takes an account name, uid or SID, resolved through the OS as for live requests. With no --user it explains the account running it, also when you pass --connector or --agent; guardrail status, status and doctor show that profile too.
defenseclaw guardrail judge add|remove CONNECTOR / judge listChoose which hook connectors forward content to the LLM judge (all means every hook connector; remove all turns the hook-lane judge off). add --enable also turns the judge on, and --timeout S caps the judge round trip on hook calls (gateway default 8 s; hook scripts allow 10 s in total). list shows the gate and each connector's effective judge state.
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 profile explain --user alice --connector codex   # as alice: a per-user install explains only your own account
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 Multi-connector for the multi-connector model.

Tool-call levels

A finding (in a prompt, a completion, a tool call or a tool response) is blocked at or above the block level and raises an alert at or above the alert level. guardrail.block_at and guardrail.alert_at are the only place these levels live, and they apply to hook tool calls, hook prompts, and proxy prompts, completions and tool calls alike. Each level resolves on its own, most specific setting first:

  1. the profile's connector entry, guardrail.profiles.<p>.connectors.<c>
  2. the profile, guardrail.profiles.<p>
  3. the connector, guardrail.connectors.<c>
  4. the connector's application protection
  5. the global guardrail.block_at / alert_at
  6. the rule pack's default (strict blocks MEDIUM+ and alerts on LOW+, default blocks CRITICAL and alerts on MEDIUM+, permissive blocks CRITICAL and alerts on HIGH+; a custom pack declares its own in the posture field of its defenseclaw-pack.json)

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. guardrail block-at and alert-at write steps 3 and 5; profiles are edited in config.yaml (see Guardrail profiles). defenseclaw config get guardrail.block_at --effective prints the level the gateway enforces and which step it came from:

defenseclaw config get guardrail.block_at --effective
HIGH
(source: config:guardrail.block_at)

The value goes to standard output and the (source: ...) line to standard error. With nothing set it reads CRITICAL and (source: pack-default:default). See Thresholds for the full model.

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

{
  "version": 1,
  "ok": true,
  "scope": "global",
  "setting": "block_at",
  "level": "MEDIUM",
  "previous": "HIGH",
  "source": "global",
  "effective_block_at": "MEDIUM+",
  "effective_alert_at": "LOW+",
  "gateway": "guardrail_off",
  "message": "The global block level is now MEDIUM: tool calls, prompts and LLM traffic are blocked at MEDIUM+ unless a connector has its own. The guardrail is off; this takes effect when you run defenseclaw guardrail enable."
}

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 Detection 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 adds NAME to the scope's guardrail.rules.protections in config.yaml. Nothing is written to the policy folder: on its next reload the gateway composes the scope's rule pack in memory from its base pack (a preset or a custom pack) plus every opt-in pack that is on, replacing base rules that have the same rule ID, and the result is part of the effective policy digest. The global scope applies to every connector; --connector X and --profile P narrow it. The command refuses a staged or unknown pack name (exit 1).

defenseclaw guardrail protection enable cloud-production-protection --json
{
  "version": 1,
  "ok": true,
  "scope": "global",
  "profile": null,
  "protection": [
    "cloud-production-protection"
  ],
  "message": "Cloud production protection is on for every connector. Only keep it on if it's true for every connector: DefenseClaw takes the pack as your word about that environment and blocks what it proves there. Saved (config generation 63). The guardrail is off; this takes effect when you run defenseclaw guardrail enable."
}

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 and use-pack results says how the saved change reached the gateway: live (the running gateway applies it on its next reload; the usual case), restarted (a hook fail-mode change), 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), restart_failed (the change is saved but the restart failed; exit 1), still_starting (saved, but the gateway was still starting, so protection is not confirmed yet; exit 1) or not_applied (the running gateway still reports the earlier config generation 10 seconds after the save: it rejected the change, which defenseclaw-gateway status names, or it never reloaded; defenseclaw-gateway restart applies it; exit 1, while the use-pack, protection, rule and suppress commands print the line and exit 0, the change being saved). A change the gateway applies except for a section it reads only at start is restart_needed too. The protection, rule and suppress commands print Saved (config generation N). and the same one-line outcome.

Policies

A named policy (default, strict, permissive, plus any you create) is a preset. policy activate copies the preset's admission actions, guardrail levels (block_at, alert_at) and Cisco trust level into config.yaml, so the active policy is the preset whose values config.yaml holds now (default when none is set). The gateway reads config.yaml, never the preset files. A preset's firewall defaults are not enforced by the gateway; OpenShell sandboxes use openshell:. policy list skips the bundled host-firewall template (firewall-deny-default.yaml) and policy activate refuses it.

CommandUse it for
defenseclaw policy create NAME [--from-preset default|strict|permissive] [--critical-action ...]Create a named policy, optionally from a preset, with per-severity install actions (block, warn, allow).
defenseclaw policy list [--json]List built-in and custom policies and mark the active one. --json prints {"version": 1, "active": "<name>", "policies": [...]}; each policy reports block_at, alert_at, install_block_at (CRITICAL, HIGH+, MEDIUM+, LOW+ or none), firewall_default, hilt, scanner_overrides, whether activating it adds webhooks of its own (adds_webhooks; your configured webhooks are always kept) or changes Cisco AI Defense settings (sets_cisco), and whether a built-in was edited (edited; shown as [built-in, edited]).
defenseclaw policy show NAME [--json]Show one policy. --json prints {"version": 1, "policy": {...}} with the same fields; exits 1 if the policy doesn't exist.
defenseclaw policy activate NAME [--reload/--no-reload]Write a preset to config.yaml (actions to admission:, thresholds to guardrail.block_at and alert_at), then by default ask the running gateway to reload. It prints Gateway reloaded the policy; it is enforcing it now., or, when the preset changes a key read only at start (a listener, guardrail.enabled, guardrail.scanner_mode; on Secure Client also watch or cisco_ai_defense), restarts the gateway and prints Restarted the gateway; it is enforcing the policy now. A stopped gateway loads it at start (exit 0). A preset's own webhooks are added when new (Added webhook <name> from the policy) or skipped on a name or URL collision (Skipped webhook <name>: ...). A rejected reload exits 1; run defenseclaw policy validate.
defenseclaw policy validate [--rego-dir DIR] / policy test [--rego-dir DIR] [-v]Check the Rego modules for errors, or run the Rego unit tests (with opa from PATH, or the runner built into defenseclaw-gateway).
defenseclaw policy delete NAME [--yes]Delete a custom policy, or your edited copy of a built-in (which restores the built-in).
defenseclaw policy edit guardrail|actions|scanner|firewall … [-p NAME] [--reload/--no-reload]Edit one section. Without -p it changes config.yaml and reloads like policy activate: guardrail writes guardrail.block_at, alert_at and cisco_trust_level; actions writes admission.defaults.actions and admission.skill.actions; scanner --type T writes admission.T.actions. With -p NAME it only saves that policy (a built-in is copied first) until policy activate NAME; policy delete NAME restores the built-in. --block-threshold and --alert-threshold take LOW, MEDIUM, HIGH, CRITICAL or a rank 1-4.
defenseclaw policy list --json | jq -r '.active'
defenseclaw policy show strict --json
defenseclaw policy activate strict              # write the preset into config.yaml + reload
defenseclaw policy activate strict --no-reload  # write it, skip the reload request
defenseclaw policy edit guardrail --block-threshold HIGH   # same as: defenseclaw guardrail block-at HIGH
defenseclaw guardrail block-at HIGH --connector claudecode   # only Claude Code: block HIGH+

A managed standalone device refuses the commands that write config.yaml (policy activate, policy edit without -p); see Managed devices. policy create, policy edit -p NAME, policy edit firewall and policy delete only change the preset files in your policy folder.

Credentials

CommandUse it for
defenseclaw keys list [--json] [--missing-only] [--show-values]Show every credential DefenseClaw knows about and where its value comes from. --missing-only keeps the required keys that are unset; --show-values shows masked previews.
defenseclaw keys set NAME [--value V | --value-stdin]Save a credential to ~/.defenseclaw/.env. Without a value option it prompts with hidden input. --value-stdin reads the first line of standard input (trailing newline removed) and never echoes it, so the secret stays out of shell history and process listings; an empty line exits 1. --value and --value-stdin can't be combined.
defenseclaw keys remove NAME [--yes]Delete a stored credential from ~/.defenseclaw/.env (any name, including ones outside the registry). It asks for confirmation unless --yes is given; a value exported in your shell is left alone. keys list names any .env entries that are not in the registry.
defenseclaw keys fill-missing [--yes]Prompt, with hidden input, for every required key that is unset.
defenseclaw keys checkExit 0 when every required key is set, 1 otherwise. For CI and preflight checks.
printf '%s\n' "$VT_KEY" | defenseclaw keys set VIRUSTOTAL_API_KEY --value-stdin

On a managed standalone device, keys set, keys remove, and keys fill-missing refuse with exit 3; use /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name <configured-credential> --from-stdin (/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS) as an administrator to rotate a credential. See Keys for the registry, resolution order, and requirement states.

Multi-connector

One gateway can protect N hook connectors at once (see 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, codeguard status) render every active connector where applicable. tool status is not a fan-out read: it needs the tool's NAME. 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 block, allow and unblock write broad fallback entries to asset_policy by default and one connector's scoped entries 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:

CommandDefault 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 [--connector X]List tool policy across active connectors; one connector when scoped.
defenseclaw tool status <name> [--connector X]Effective policy for the named tool; one connector when scoped.
defenseclaw codeguard status [--connector X]CodeGuard install state across active connectors by default; one connector when scoped.

Audit & alerts

CommandUse it for
defenseclaw alerts [--connector X] [--json]Snapshot of recent alerts (default 25). --connector X filters by connector; --limit N widens the window; --show <n> prints one full record. A finding row names its target, decision (blocked, would block (observe mode), detected in the prompt (cannot block)), rule, scanner, ACP route or sandbox. --json adds target, decision, rule, scanner, location, route, path, moved_to next to the raw details. Detection-only findings are not alerts; the list ends with how many there were in the last 24 hours, and defenseclaw audit export --since 24h lists them as scan-finding rows. An empty list says No alerts.
defenseclaw alerts acknowledge / dismissAcknowledge or dismiss alerts. The gateway records the change, so it must be running. Select them with --id, --connector, --target, --since, --before, or --severity all|CRITICAL|HIGH|MEDIUM|LOW|ERROR|INFO; --dry-run shows what would change.
defenseclaw-gateway audit export (or defenseclaw audit export, same options)JSONL export of audit_events, oldest first, with structured when present. --limit N returns the earliest N matches, or with --newest the most recent N. --since (inclusive) and --until (exclusive) take RFC3339 or a duration ago (30m, 2h). --connector keeps one connector's rows. --db PATH reads another audit database, for example ~/.defenseclaw/previous/data/audit.db after a rollback. Configuration changes are audit rows with action config.change.applied; structured names the operation (defenseclaw.admin.operation, for example config-update) and what changed (defenseclaw.admin.target_ref). --include-activity also appends rows of the activity_events table, which holds only pre-1.0 history.
defenseclaw audit logs [--source gateway|watchdog] [-n N] [--grep TEXT]Print the newest lines of ~/.defenseclaw/gateway.log (or watchdog.log), the same log the TUI Logs panel shows. -n defaults to 50; --grep keeps lines that contain the text (case-insensitive). For config changes and operator actions use defenseclaw audit export --since 1h: they are audit rows with action config.change.applied and others.
defenseclaw-gateway audit findings [--since RFC3339] [--new-only] [--include-resolved] [--scanner NAME] [--target PATH] [--limit N] (or defenseclaw audit findings, which runs it with the same options)Report the deduplicated finding lifecycle. Active current findings are the default; --include-resolved adds resolved state, while --since selects lifecycle changes and --new-only narrows that window to fingerprints first observed since the timestamp. JSON reports both the total distinct count and the returned page.
tail -f ~/.defenseclaw/gateway.jsonl | jqTail an optional, explicitly configured kind: jsonl destination at that path. It holds only the records routed to that destination; complete local history stays in SQLite, and 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.

CommandUse 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|disableConfigure 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] [--sandbox NAME] [--show-gone] [--by-detector] [--wide] [--json]Read the sidecar snapshot. Local-model rows show model ID and installed/loaded status (--wide adds format, version and identity/presence confidence); --component also matches model IDs; --sandbox keeps what AI discovery found inside that OpenShell sandbox, whose rows every view tags "(sandbox NAME)". active remains an alias for the steady seen lifecycle state. JSON output is the unfiltered API payload.
defenseclaw agent identities [--user U] [--connector C] [--limit N] [--json]List every agent identity (agt-...), or the N most recently seen, one per connector install, user and machine, with their session count, last seen time and config root.
defenseclaw agent ide-plugins [--user U] [--ide IDE] [--ai-only] [--json]List every IDE extension and plugin per user (User, IDE, Plugin, Version, Enabled, AI) from the gateway's last full scan. See IDE plugin inventory.
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 components show|history NAME [--ecosystem ECO]Every place one component was detected, or its confidence over the last scans.
defenseclaw agent confidence explain NAME / confidence policy show|default|validateThe per-evidence confidence breakdown for one component, and the confidence-scoring policy: the active one, the built-in default (a starting point for an override file), or a dry run of a candidate file.
defenseclaw agent signatures list|validate|install|enable|disableManage AI discovery signature packs: list the merged catalog (--include-disabled), validate or install a pack, and turn one signature ID off or back on.

Runtime discovery watches what AI software does while it runs (inference traffic, unknown AI egress, agent actions) and is configured under ai_discovery.runtime:

CommandUse it for
defenseclaw agent discovery runtime permissions [--grant] [--revert] [--os OS]What each runtime plane needs on this host and how to grant it; works before anything runs. --grant applies the missing grants after showing every command.
defenseclaw agent discovery runtime enable|disableTurn the runtime planes on (--enable-host-plane for kernel events, --dns-capture, --poll-interval-s, --min-risk-to-report) or off. Recorded findings are kept.
defenseclaw agent discovery runtime status|selftestWhat each plane can and cannot see right now, and why.
defenseclaw agent discovery runtime findings [--severity S] [--limit N] / runtime scanList the scored runtime findings, or poll the planes now.
defenseclaw agent usage --refresh --category local_model --detail
defenseclaw agent usage --component Qwen3
defenseclaw agent usage --state seen
defenseclaw agent usage --show-gone
defenseclaw agent ide-plugins --user alice --ai-only
defenseclaw agent identities --connector codex

See AI Discovery for model servers, file formats, lifecycle 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.

CommandBinaryUse it for
defenseclaw skill scan [target] [--connector X] [--all] [--path DIR] [--remote] [--action]defenseclawScan a configured skill, a path (--path DIR, or the path as target; target is optional with --path), a URL (https://… / clawhub://…), or every configured skill with --all. A bare skill name searches matching configured connector copies; --connector X narrows. --all --json always emits one top-level result array, including per-skill error rows, before returning nonzero for scanner failures; a telemetry-recording warning never discards or fails a completed scan.
defenseclaw mcp scan [target] [--connector X] [--all] [--scan-prompts] [--scan-resources] [--scan-instructions]defenseclawScan 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] [--include-self]defenseclawScan one plugin/extension package, or all discovered plugins with --all. --connector X narrows discovery or duplicate plugin names to one connector. Exact first-party DefenseClaw package/connector artifacts are excluded by default; --include-self opts into scanning them for product development. Ordinary third-party dist/ trees and plugins merely named defenseclaw remain in scope.
defenseclaw aibom scan [--connector X] [--json] [--summary] [--only <cat>]defenseclawBuild the agent SBOM (skills, MCP, plugins, models, sinks) for every active connector by default, or one connector when scoped. --only takes a comma-separated list of skills, plugins, mcp, agents, rules, tools, models, memory, ide_plugins (the IDE plugin inventory, read from the gateway); an unknown name exits 2.
defenseclaw registry sync [source...] [--all] [--scan]defenseclawSync registries; with --scan, runs the scanner pipeline against every fetched entry.
defenseclaw codeguard {status,install,install-skill} [--connector X]defenseclawManage the CodeGuard skill/rule install across active connectors by default, or one connector when scoped.
defenseclaw-gateway scan code <path> [--json] [--no-redact] [--schema]defenseclaw-gatewayScan source files in <path> using the bundled CodeGuard rule pack. The version-7 CLI schema preserves safe context in its declared location/line_number fields while replacing detected sensitive substrings; detached REST/API responses may additionally expose a structured file field. --no-redact is an explicit local-stdout-only opt-in, requires --json, and prints a warning; the REST API remains protected. Runs in-process and does not require the sidecar daemon.

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.

CommandUse it for
defenseclaw skill block|allow|unblock <name> [--reason R] [--connector X]Put a skill on the install block list or allow list in config.yaml, or take it off (unblock takes no --reason). Without --connector, matching configured connector copies are handled together or the unscoped fallback is written; --connector X targets one connector copy. allow also removes the skill from the block list.
defenseclaw skill disable|enable|quarantine|restore|install <name> [--connector X]Runtime and file actions: disable or re-enable a skill at runtime, move its files to the quarantine area and back, or install a ClawHub skill. These are not policy; see the table below.
defenseclaw mcp block|allow|unblock <name-or-url> [--reason R] [--connector X]The same for an MCP server, by name or URL. unblock clears the server's block, allow, quarantine and disable entries so its scan verdict decides again.
defenseclaw mcp set|unset <name> [--connector X]Add, update or remove an MCP server in the connector's own MCP config. mcp set / unset write every configured connector source by default; --connector X writes one connector's MCP source. This edits the agent's config, not config.yaml. For Claude Code, set writes ~/.claude.json and removes a same-named entry that 0.8.x left in ~/.claude/settings.json; unset removes the name from both.
defenseclaw plugin block|allow|unblock <name> [--reason R] [--connector X]The same for a plugin.
defenseclaw plugin remove|disable|enable|quarantine|restore|info <name> [--connector X]Remove a plugin's files, disable or re-enable it, quarantine or restore it, or show its details, across configured connector copies by default or one connector when scoped.
defenseclaw tool block|allow <name> [--connector X] [--source S] [--reason R]Put a tool on the block or allow list. Bare rules are the fallback tier for every configured connector. A connector-scoped rule (--connector X, or the name given as @X/<name>, the form tool list shows) is stored as the tool name with connector: X in asset_policy.tool. --source is recorded for audit only: hook payloads carry no tool source, so a source-scoped block is enforced as an unscoped block, and a source-scoped allow, which would never apply, is refused. After it writes, the command waits up to 5 seconds for the running gateway and says The running gateway enforces it now (policy digest <12 characters>). or Pending: the running gateway has not applied it yet. Hook calls keep the previous verdict until it reloads config.yaml, usually within a few seconds. It says nothing when no gateway answers.
defenseclaw tool unblock <name> [--connector X] [--source S]Remove a tool from the block/allow list. Without --connector or --source it removes the fallback entry and the connector-specific overrides for this tool. It prints the same enforcement line.
defenseclaw tool status <name> [--connector X] [--source S] [--json]Show the effective policy for one tool.
defenseclaw tool list [--blocked|--allowed] [--connector X] [--json]List tool policy entries. UPDATED is - for an entry in config.yaml, which records no time for it.
defenseclaw skill info <name> [--connector X] [--json] / plugin infoShow one skill's or plugin's details.
defenseclaw skill search QUERY [--json]Search the remote ClawHub registry of installable skills (not the skills already installed). Uses a local clawhub binary or a cached npx clawhub.
defenseclaw plugin install NAME_OR_PATH [--connector X] [--action] [--force]Install a plugin from a local directory, an npm package, ClawHub, or a URL into each configured connector with a supported install directory (or one with --connector), then scan it. Codex requires its own marketplace install flow: this command refuses a Codex-only install and names Codex when skipping it during a multi-connector install. --action applies the admission.plugin actions to the scan result; without it, a plugin the admission policy rejects is not installed and the install fails. --force replaces an existing plugin, only once the new copy is admitted.

Where block and allow state lives

Two kinds of verb look alike and differ in where they keep state:

VerbsStateGateway call
block, allow, unblock on skill, mcp, plugin and toolasset_policy.<type>.denied and asset_policy.<type>.allowed in config.yaml, written through the config writer. The explicit lists apply in every asset_policy.mode. The running gateway applies the change on its next reload, so the effect needs no restart.None. With the gateway stopped, the change is still saved and the command warns that the audit event was not recorded.
disable, enable, quarantine, restore on skill and pluginRuntime state: the enforcement journal in audit.db, plus the files a quarantine moves. These are not block or allow lists and are not in config.yaml. A Claude Code plugin quarantine also turns the plugin's enabledPlugins entries in ~/.claude/settings.json off, so claude plugin list shows it disabled; restore turns those entries back on and leaves the others as they are.disable and enable call the running gateway and fail when it cannot be reached.

Nothing reads the actions table of audit.db as a block or allow list any more. A config_version 8 install that has operator block or allow entries there has them moved into asset_policy by the one-time migration.

defenseclaw skill block evil-skill --reason "supply-chain advisory"
defenseclaw config get asset_policy.skill.denied --format json
[skill] Blocked 'evil-skill' (every connector).
[
  {
    "name": "evil-skill",
    "reason": "supply-chain advisory"
  }
]

Fields that are not set (connector, command, url and the others) are left out.

Lifting it is the same command family, and the entry leaves config.yaml:

defenseclaw skill unblock evil-skill
[skill] Unblocked 'evil-skill' (every connector).
  It will be scanned on the next check.

Because these are ordinary config.yaml keys, you can also edit the lists directly with config set and config unset, for example defenseclaw config set 'asset_policy.skill.denied[0].name' evil-skill. See Admission for what the lists, the scan gate and the registry rules decide together.

On a managed standalone device the three policy verbs are refused with exit 3 and change nothing; see Managed devices. quarantine, restore, disable and enable stay available there.

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 a running sidecar for you, and the sidecar applies a valid change to config.yaml by itself, with no restart, unless the change touches a restart-required key. Running defenseclaw-gateway with no arguments starts the sidecar in the foreground.

On a managed Windows computer status, audit findings and connector list-backups have no per-user gateway to read and exit 1, and the managed help hides start, stop, restart and watchdog, which are not for a managed computer; see Managed devices.

CommandUse it for
defenseclaw-gateway startStart the sidecar as a background daemon.
defenseclaw-gateway stopStop the running sidecar.
defenseclaw-gateway restartRestart the sidecar.
defenseclaw-gateway status [--json]Health snapshot of the daemon, with a per-connector Connector Mode section from /status connector_modes. --json prints running, endpoint, the /health snapshot as health, or error and hint; exit 1 when the gateway does not answer. On a managed Linux computer whose sensor helper reports Plane C, the Subsystems list ends with Kernel sensor: Tetragon v1.7.1 (consume), then ; kernel controls: enforcing 2 of 3 users when controls are loaded, or cn_proc and fanotify (Tetragon not used: <reason>) on the fallback. See Tetragon.
defenseclaw-gateway watchdog [start|stop|status]Health-watchdog daemon that notifies when the gateway is down and, on Linux and macOS, starts a per-user gateway whose process stopped on its own.
defenseclaw-gateway policy reloadAsk the running daemon to reload its OPA policies without bouncing it.
defenseclaw-gateway policy validate|test [--rego-dir DIR]Compile-check the Rego modules and the admission policy compiled from config.yaml, or run the Rego unit tests without a separate opa binary. On a managed host, which ships no Rego, validate says so (on Windows No policy_dir is set, so the gateway loads no Rego: the admission policy is compiled from config.yaml alone.) and prints where each admission policy comes from, and test says there is nothing to run; both exit 0.
defenseclaw-gateway policy showPrint the admission policy and guardrail levels compiled from config.yaml.
defenseclaw-gateway policy digest [--json]Compute the effective policy digest from config.yaml and the policy assets it names (rule packs, Rego modules, signature packs, scanner policies), the way the gateway does when it applies a configuration. Compare it with policy.effective_digest on the gateway's /health to see whether the running gateway applies this configuration. See Policy generation and digest. Secure Client does not provide policy digest; it returns an unknown-command error.
defenseclaw-gateway policy evaluate [--target-type T] [--target-name N] [--severity S] [--findings N]Dry-run the admission policy for one input.
defenseclaw-gateway rulepack validate [--dir DIR] [--json]Validate a rule-pack directory the way the gateway does when it loads one, without starting it; without --dir it validates the embedded default pack. defenseclaw guardrail validate-pack runs this.
defenseclaw-gateway config validate [FILE] [--json] [--data-dir DIR]Read-only check of a candidate config.yaml with the compiler and loader the gateway runs at start: schema, guardrail profiles and assignments, every profile's sandbox floor combined with openshell.admin, rule packs and destinations. A managed standalone file also gets the layout rules ensure applies (every OS refuses a gateway.api_bind other than 127.0.0.1, and Linux and macOS also refuse a gateway.api_port other than 18970; on a managed computer data_dir too). A refusal names the setting and the profile, for example guardrail.profiles["contractors"]: sandbox: allowed: false contradicts required_for [claudecode]. Exits 1 when the gateway or ensure would refuse the file. Without FILE it checks the installed config: on a managed computer, the managed one.
defenseclaw-gateway config migrate [--dry-run] [--json] [--ack] [--config FILE] [--data-dir DIR] [--to 9]The migration that defenseclaw config migrate and defenseclaw migrate run: moves policies/rego/data.json, the *_actions keys, rule_pack_dir, the v8 scanner keys, update_check and, on a per-user install, the operator block and allow entries of audit.db into config.yaml. See Upgrade.
defenseclaw-gateway provenance showPrint the config schema version, content hash, generation, and binary version.
defenseclaw-gateway connector reconcile|verify|teardown|list-backups [--connector X] [--json]Low-level lifecycle for one connector, outside the setup flow: refresh its installed registration, check it left no residual state, remove its config patches, or list its pristine backups. Without --connector it uses the active connector. defenseclaw uninstall uses these.

TUI

CommandUse it for
defenseclaw tuiOpen the interactive operator UI for audit, alerts, logs, inventory, and setup. It does not provide a resumable approval queue for hook calls. See TUI.

Configuration

config.yaml is the only file where you choose DefenseClaw's settings. The config group reads it, changes it through the config writer, and migrates it. Everything else under ~/.defenseclaw/ is derived from it (rewritten for you, never read back), evidence of what was applied, or runtime state. See Configuration: one source of truth for the model and Configuration for every key.

CommandUse it for
defenseclaw config get KEY [--effective] [--format yaml|json]Print one value or a whole section (secrets masked). A key config.yaml leaves out prints its default and says so on stderr. With --effective, guardrail levels (guardrail.block_at, guardrail.connectors.C.alert_at) and admission[.<type>] resolve the value from the current config.yaml and print its source on stderr: config:<key>, pack-default:<pack>, derived:scanners.skill_scanner or builtin (the shipped admission defaults). An admission key config.yaml leaves out prints that resolved value without the flag too. Exit 1 when the key has no value and no default, 2 for an unknown section.
defenseclaw config set KEY VALUE [--json] [--expect-sha256 S]Change one value through the config writer. KEY is a dotted path with [i] list indexes; VALUE is a YAML scalar, or any JSON value with --json. See config set and config unset.
defenseclaw config unset KEY [--expect-sha256 S]Remove a key, so its default applies again.
defenseclaw config show [--section NAME] [--source] [--format yaml|json]Print the whole configuration, or one top-level section, with the defaults that apply to the keys config.yaml leaves out. --source prints config.yaml as written, unresolved. --effective (with optional --provenance) prints only the observability section, resolved the way the gateway runs it.
defenseclaw config validate [--quiet]Check that config.yaml parses and uses valid values. Exit 0 valid, 1 not. --quiet only sets the exit code.
defenseclaw config pathPrint the files and directories DefenseClaw uses.
defenseclaw config reference [observability] [--format yaml|json-schema|markdown] [--output FILE]Print this release's configuration reference. --format json-schema covers every section with each field's allowed values.
defenseclaw config migrate [--dry-run] [--ack] [--json]Migrate config.yaml to config_version 9, or acknowledge the migration. See Upgrade.
defenseclaw settings saveWrite the current resolved configuration to disk and record an activity event, as the TUI Setup panel does.

Read a section or a key

A section prints as YAML, or as JSON with --format json. A single key prints its value alone; when config.yaml does not set it, the default is printed and the note goes to standard error:

defenseclaw config get guardrail.mode
defenseclaw config get guardrail.hilt
defenseclaw config get guardrail.hilt --format json
observe
(default: config.yaml does not set guardrail.mode)
enabled: false
min_severity: HIGH
{
  "enabled": false,
  "min_severity": "HIGH"
}

A key that 1.0 no longer reads (a retired key, such as openshell.version) has no default: config get says it is not set.

To read one item of a list, put its number in the path: config get asset_policy.skill.denied.0.name. config get also takes the spelling config set and config unset use, asset_policy.skill.denied[0].name.

--effective resolves the current config.yaml using gateway policy rules and shows where the value comes from. It does not query the running gateway. The value goes to standard output and the source to standard error:

defenseclaw config get guardrail.block_at --effective
CRITICAL
(source: pack-default:default)

After defenseclaw config set guardrail.block_at HIGH the same command prints HIGH and (source: config:guardrail.block_at). If a hand edit causes a rejected reload, this command can show the new file value while the gateway continues to enforce its previous generation. Check defenseclaw status or defenseclaw doctor to see whether the latest configuration was applied.

config set and config unset

Every write goes through the one config writer that the Go gateway, the Python CLI and the TUI share. It takes the config.yaml.lock file lock, checks the whole result (schema and the references between sections, such as a rule pack digest) before it writes, replaces the file atomically, and records the write in config.generation.json. A running gateway notices the new file and applies it; a change it cannot apply leaves the previous policy running.

defenseclaw config set guardrail.block_at HIGH
Set guardrail.block_at (config generation 7, sha256 a3aa87865757).
Effective policy digest: sha256:61dc3164f6ee3fd8ac25a49ebf47b43488032efd63d1ee2ae7f2c3101fc5a550

The first line names the config generation and the first 12 characters of the new file's SHA-256; the second is the effective policy digest the gateway will report once it applies the change. Setting a key to the value it already has changes nothing and says so (guardrail.block_at already has that value (generation 7).). VALUE is read as config.yaml is: only true and false are booleans; finite decimal numbers such as 3.5 are accepted. Thus off, on, yes and no are text and defenseclaw config set ai_discovery.ide_inventory off sets that enum value. config unset also removes the parent maps it leaves empty, up to the section or named entry where empty means something (a whole section, or an entry such as guardrail.connectors.codex), so a config set followed by the same config unset leaves no empty scanners: {} behind. An entry that is what puts a connector on the roster stays. config unset of a key that is not set says its default already applies, and exits 1 for a key that does not exist, such as a misspelled one. Neither command changes config_version: only defenseclaw migrate does. Unsetting a whole connector entry, such as guardrail.connectors.codex, takes that connector out of the guardrail roster: the gateway removes its hooks and stops guarding it, and the command says so and names defenseclaw setup <connector> to guard it again. To pause a connector on purpose use defenseclaw guardrail disable --connector <connector>; to change one of its settings, name the key, for example guardrail.connectors.codex.mode.

  • A list item or a whole value as JSON. Quote a path that has brackets in your shell, and use --json for anything that is not a single scalar:

    defenseclaw config set 'asset_policy.skill.denied[0].name' evil-skill
    defenseclaw config set asset_policy.skill.denied --json '[{"name":"alpha","reason":"test"},{"name":"beta"}]'
    defenseclaw config unset 'asset_policy.skill.denied[0]'
    Set asset_policy.skill.denied[0].name (config generation 4, sha256 1dc3958e3d68).
    Effective policy digest: sha256:0b8b48f274f484a3ed1d80a9f671300db7463499c9531fa405eb59aa0e6c33bc
    Set asset_policy.skill.denied (config generation 5, sha256 c125588555e0).
    Effective policy digest: sha256:a0ec2d0f348516bb71d414e7de49d1f5bb20b8f4107707dff0fa3a33f02c7f3f
    Unset asset_policy.skill.denied[0] (config generation 6, sha256 f79b4307cc83).
    Effective policy digest: sha256:d705e2607d549cf05de07ee29d9cb36c3203efa59d6b7513e4ded7adcd98ed77

    After those three commands defenseclaw config get asset_policy.skill.denied --format json prints [{"name": "beta"}], laid out over several lines.

  • Guard against a concurrent edit. --expect-sha256 refuses the change unless config.yaml still has the SHA-256 you read. The full digest of the current file is config_sha256 in config.generation.json, or sha256sum config.yaml:

    H=$(sha256sum ~/.defenseclaw/config.yaml | cut -d' ' -f1)   # macOS: shasum -a 256
    defenseclaw config set guardrail.alert_at MEDIUM --expect-sha256 "$H"

    A stale digest prints Error: config.yaml changed since --expect-sha256 was read; read it again and exits 1; nothing is written.

  • A rejected value. The writer refuses a value the schema does not allow and leaves config.yaml as it was (exit 1):

    defenseclaw config set guardrail.block_at BOGUS
    Error: config.yaml was not changed: guardrail.block_at is not in the expected format. Use one of CRITICAL, HIGH, MEDIUM, LOW in any case (empty inherits).

    The schema that names itself v8 accepts config_version 8 and 9 files. A key the schema does not know is rejected the same way. A malformed path or invalid --json exits 2.

  • A key that needs a restart. The change is written and the command tells you what to do:

    Set gateway.api_port (config generation 8, sha256 40e277a85345).
    Effective policy digest: sha256:0b1ae6b5c17824f8189e388cfef40584bbc974651f0795450d08b9736b1b78de
    Restart the gateway to apply gateway.api_port: defenseclaw-gateway restart
Exit codeconfig set / config unset
0Written, already had that value, or (unset) already at its default. A change that was saved exits 0: if the gateway did not confirm the audit event (for example it is stopped or restarting on a new port), one warning says the change was saved
1Refused: invalid value or reference, a stale --expect-sha256, or another process holds the config lock
2Malformed KEY or --json value
3The device is managed; see below

Restart-required keys

A running gateway applies every other change itself. A change to one of these is saved, but the running gateway keeps the old value until you run defenseclaw-gateway restart, and config set names the key after it saves:

  • data_dir, deployment_mode, enterprise.profile, enterprise.network, enterprise.openshell, environment, tenant_id, workspace_id and discovery_source
  • gateway.* (the listener, authentication and upstream keys), except gateway.watcher.* and gateway.config_reload.* other than gateway.config_reload.mode
  • guardrail.host, guardrail.port, guardrail.enabled, guardrail.connector, guardrail.scanner_mode, guardrail.retain_judge_bodies, guardrail.hook_self_heal and guardrail.hook_self_heal_debounce_ms
  • claw, agent, routing and plugin_dir
  • observability.local.path and observability.local.judge_bodies_path
  • fleet.enabled, fleet.mqtt_broker_url, fleet.mqtt_require_tls, fleet.ota_key_env, fleet.emergency_key_env, fleet.device_key_env, fleet.mqtt_user_env and fleet.mqtt_pass_env

The storage paths (data_dir and the two observability.local paths) and deployment_mode are the exception: the gateway can not keep their old value, so it refuses that reload, and every later one, until you restart it. /health shows the error as last_reload_error, and an /enforce write answers applied: false.

Thresholds, rule packs and rules, suppressions, guardrail.hook_fail_mode, the connector set (guardrail.connectors.<c>.enabled), admission, asset_policy, scanners, llm_providers, update and the observability destinations and redaction profiles all apply without a restart. The TUI follows the same list; see TUI.

Managed devices and exit code 3

On a managed standalone device the administrator owns config.yaml (it is delivered by MDM or a management plane), so the writer refuses local changes. config set and config unset print the reason to standard error, change nothing, and exit 3:

error: This device is managed: change config.yaml in the admin config (MDM or management plane), not on the device

skill, mcp, plugin and tool block, allow and unblock are refused the same way, with a message that the asset_policy block and allow lists are set in the admin config (MDM or management plane), and exit 3. When the Python CLI is used against a managed config, a standard user with no per-user config is not sent to defenseclaw init: init, quickstart and every command that needs a config print This device is managed: DefenseClaw is configured by your administrator (MDM or management plane), so there is no per-user config to create and 'defenseclaw init' does not apply. Nothing was changed. and exit 3. defenseclaw doctor in that state skips the per-user checks with the same notice and exits 3; an administrator checks the device with /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status (/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status on macOS). guardrail ... writers are also refused on a managed standalone device. For example, guardrail block-at prints This device is managed: change config.yaml in the admin config (MDM or management plane), not on the device and exits 3. policy activate is refused there too (the Windows package has no policy activate; see below). Where the Python CLI is installed, config get, config show, config validate and status still work.

A standard user on a Linux or macOS computer with the standalone enterprise package does not get the Python CLI. The defenseclaw command there runs only the commands in Managed command availability. Every other command, readers included (doctor, config get, skill list), prints "This computer is managed; use defenseclaw status for your protection state, defenseclaw sandbox status for your sandboxes and defenseclaw sandbox policy explain for your policy." followed, on Linux and macOS, by the administrator views of that computer (the installed gateway's enterprise linux status or enterprise macos status, verify and audit export --since 2h) and exits 2, not 3. defenseclaw-gateway is not on that user's PATH. The administrator runs it by its packaged path, as root (/opt/defenseclaw/bin on Linux, /opt/cisco/defenseclaw/bin on macOS).

Windows has no sandbox-only command. There defenseclaw.exe is the administrator's command: the gateway binary, not the Python CLI. It answers setup, doctor, upgrade and rollback with a note that the computer is managed and exits 1. With --help they print that note with their usage and exit 0. config set prints This device is managed: change config.yaml in the admin config (MDM or management plane); config set did not change it (config unset says config unset) and exits 3; the block, allow and unblock writers are refused with exit 3 too. These answers name the administrator's next command: skill, mcp, plugin and tool name policy show, setup names enterprise windows status --profile standalone, and sandbox (sandboxes do not run on Windows, exit 3) names & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe' enterprise windows sandbox list --user NAME, each from an elevated PowerShell prompt. Its guardrail commands are refused with exit 3 like config set (guardrail disable prints This device is managed: change config.yaml in the admin config (MDM or management plane); guardrail disable did not change it). It has no version command (run & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' --version) and no policy activate or policy edit: these return an unknown-command error and exit 2. Its policy group has digest, evaluate, reload, show, test and validate. Commands that read a per-user gateway, such as audit findings and connector list-backups, exit 1 with this computer's DefenseClaw is managed by your organization, say the command has no per-user deployment to check and name the administrator's enterprise windows status --profile standalone, also from an elevated prompt; audit export works there. status run by a standard account shows that account's own Claude Code and Cowork protection state and its own last Cowork event (--json adds deployment_mode: managed_enterprise), which the gateway service answers for the account that asks; from an elevated prompt it gives the answer above. A standard account's enterprise windows status or verify only says that it needs an elevated prompt. The administrator runs & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise ... from an elevated PowerShell prompt. Setup puts no DefenseClaw command on PATH.

The Windows package's init and quickstart are not shipped: they return an unknown-command error and exit 2. Its doctor prints administrator guidance and exits 1, including with --passive or --json; it does not run the Python doctor's checks. Its config group has only validate and migrate: there is no config get or config show. From an elevated prompt, an administrator checks the managed config with config validate 'C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml', reads the compiled admission policy with policy show, and checks an account's agents with enterprise policy show --user NAME. These package commands do not share the Python CLI's no-config exit 3 contract.

Registries

External skill and MCP catalogs. See Registries.

CommandUse it for
defenseclaw registry wizardInteractive add-and-sync for a first catalog. defenseclaw setup registry runs the same wizard.
defenseclaw registry add [SOURCE_ID] --kind K --url U [--content skill|mcp|both] [--auth-env NAME] [--non-interactive]Register a source. Kinds: clawhub, smithery, skills_sh, http_yaml, http_json, git, file.
defenseclaw registry edit SOURCE_ID ... / remove SOURCE_ID [--keep-cache]Change only the flags you pass, or delete a source and its cache.
defenseclaw registry list / show SOURCE_IDList sources, or show one with a summary of its verdicts.
defenseclaw registry test SOURCE_ID [--show-entries]Fetch and parse a source's manifest without writing the cache.
defenseclaw registry sync [SOURCE_ID...] [--all] [--scan/--no-scan] [--no-promote]Fetch, scan, and promote entries from one or more sources.
defenseclaw registry entries SOURCE_ID [--type T] [--status S]Show the cached entries of a source after a sync.
defenseclaw registry approve|reject SOURCE_ID ENTRY_NAME [--type skill|mcp]Approve an entry so it promotes despite warnings, or reject it so it never promotes.
defenseclaw registry require --type skill|mcp --enabled|--disabled [--connector C]Require skills or MCP servers to come from a registry (asset_policy.<type>.registry_required). The running gateway applies the asset policy without a restart; on a Secure Client computer a registry command that changed it restarts the gateway.

Every registry command takes --json, except wizard.

Upgrade

CommandUse it for
defenseclaw upgrade [--version X.Y.Z] [--yes]Download the latest (or the given) release's installer, check it against that release's checksums.txt, and run it. The installer keeps your configuration and data, migrates them, restarts the gateway, and restores the previous install if anything fails. See Upgrade DefenseClaw. --version without a value (or followed by another option) exits 2 with --version needs a release number, for example: defenseclaw upgrade --version 1.2.3, and changes nothing.
defenseclaw rollback [--yes]Swap the live install with the one the last upgrade replaced. Run it again to roll forward.
defenseclaw migrate [--check] [--from-version X.Y.Z] [--data-dir DIR] [--json]Bring configuration and data to this version's schema, including the config_version 9 step below. The installer runs it on every upgrade; --check lists the pending steps and changes nothing. Exits 2 for a configuration written by a newer release. --from-version names the release that wrote the data; a value newer than this release prints a warning. An empty config.yaml is refused (exit 1) with the repair: restore your copy or remove it and run defenseclaw init.
defenseclaw config migrate [--dry-run] [--ack] [--json]Run only the config.yaml step: migrate to config_version 9, preview it with --dry-run, or mark the record as read with --ack. With no migration record, --ack says There is no config_version 9 migration record (<path>); nothing to acknowledge.
defenseclaw-gateway config migrate [--dry-run] [--ack] [--json]The same migration from the Go binary, which both Python commands call. --config FILE and --data-dir DIR select the file; --to is the target version (default 9). The gateway also reads a version 8 file as version 9 in memory when it loads it, so it starts either way.

Migrate config.yaml to version 9

A fresh defenseclaw init writes config_version: 9. Run defenseclaw migrate --check to see what is pending, then defenseclaw migrate (or the upgrade, or defenseclaw config migrate) to apply it. A real run keeps config.yaml.v8.bak, writes migration-v9.json and renames a retired policies/rego/data.json to data.json.migrated-v9. defenseclaw doctor shows a Config migration row until you run defenseclaw config migrate --ack. Running the migration on a version 9 file prints config.yaml is already config_version 9; nothing to migrate. and changes nothing.

The moved keys, sample output and the way back are in Migrate to config version 9.

Uninstall / disable

CommandUse it for
defenseclaw setup guardrail --disableRoll back guardrail. Connector files restored from backup.
defenseclaw uninstallReversible by default — runs connector teardown (removes the hooks and registrations), stops the sidecar, removes the OpenClaw plugin, leaves ~/.defenseclaw/ (audit DB, config, secrets) and the binaries intact.
defenseclaw uninstall --allSame as above, plus deletes all of ~/.defenseclaw/ (hook scripts and foreign-hooks-backup included) and the local observability stack's containers and data volumes. The launcher links into ~/.defenseclaw/ go with it; the binaries stay. It also removes the MCP writer's backup files beside agent configs that no registry entry names.
defenseclaw uninstall --all --binariesRemoves everything: all of the above, plus defenseclaw-gateway, defenseclaw-acp, the hook helpers (defenseclaw-hook-post, defenseclaw-hook-user and, on Linux, defenseclaw-sensor-helper), the launcher links, the uv the installer added (when unchanged) and its bookkeeping from ~/.local/bin (%USERPROFILE%\.local\bin on Windows, where the emptied folder and its user Path entry go too). On macOS, DefenseClawMac.app stays; the plan says how to remove it. Run --dry-run first to see the plan.
defenseclaw uninstall --keep-openclawLeave the OpenClaw config and plugin in place; the other connectors' teardown still runs.
defenseclaw uninstall --skip-sandbox-teardownUninstall without the OpenShell sandbox teardown it runs first (when Docker or OpenShell are gone or broken); defenseclaw sandbox teardown removes the sandboxes later. reset takes it too.
defenseclaw uninstall --stop-sandboxesStop and delete running OpenShell sandboxes during teardown, including copy-mode work not pulled back. Without it, a running sandbox stops uninstall before any change. For copy mode, use defenseclaw sandbox pull NAME --apply (or --branch or --patch-out FILE) and confirm the project, branch or patch file contains the work before defenseclaw sandbox stop NAME. For mount mode, use defenseclaw sandbox review NAME before stopping it. reset takes this option too.
defenseclaw reset --yesWipe ~/.defenseclaw/ so defenseclaw quickstart starts clean — keeps binaries and the OpenClaw plugin in place. Like uninstall, it prints the Cowork removal step when setup cowork built a plugin.

On Windows, uninstall also removes a DefenseClaw Setup 0.8.x install that the installer left in place because its data is in another folder (DEFENSECLAW_HOME). It stops that install, removes its program folder, cached Setup, Apps & Features entry, sign-in start and PATH entry, and turns its hook launcher off. It never runs that install's programs and keeps its data folder.

If part of that removal stays, uninstall exits 1 and prints one next step for each reason: close the program that holds a file, ask an administrator to remove what your account cannot, or sign in as the account that owns the folder. The step names the path. For a link at or above the Setup folder it names the link and its kind (junction or symlink), and tells you to remove only that link with cmd /c rmdir "<link>" (this removes the link, not the folder it points to) if it is stray, or to ask an administrator to; if the link is part of how your profile is set up, leave it. DefenseClaw does not read or remove anything through a link.

The same rule holds on Windows for the folders uninstall removes from your profile (the data folder, the install folder, the folders Setup left under %LOCALAPPDATA%\DefenseClaw, the connector backups it moves out of the data folder, the MCP config backups, the Copilot plugin, and uv's cache entries and folders): a link at the folder or above it keeps the folder, and uninstall names the link and the step above. Just before the removal uninstall also checks that the real path is the path written: short 8.3 names and letter case do not matter, a drive mapped to a network share (such as a home drive) is its share, and a subst drive is refused and named (subst X: /d removes the substitution). If the real path cannot be determined at all, the folder stays and the reason says so (ask an administrator). For a reparse point that is neither a junction nor a symbolic link (an online-only OneDrive folder, a deduplication or WSL point) the step is to ask an administrator; a volume mount point counts as a junction, and rmdir on it removes only the mount. The editor entries of an ACP setup and the empty Cowork marker folder beside the data folder are not checked this way. A link at the Setup folder whose target cannot be found (a deleted folder, or a drive or share that is not connected) is named too; if it is stray, cmd /c rmdir "<link>" removes only the link, and if the drive or share should be there, connect it. A link further up whose target cannot be found is named only when Setup left its entries in your registry (Apps & Features, sign-in start) or its hook launcher state; otherwise it is not a reason for uninstall to exit 1.

After it stops the gateway, uninstall removes this account's port claim files (defenseclaw-api-port-<port> and defenseclaw-guardrail-port-<port>): in C:\ProgramData on Windows, in /var/tmp on Linux and macOS. The gateway leaves them so that init on another account does not take its ports. Only the ports of the gateway that was stopped, and only files that belong to this account, are removed; the next gateway start claims its ports again.

uninstall and reset cannot remove the Claude Cowork plugin that defenseclaw setup cowork adds to your Claude account, and they say so when one was built. In Claude Desktop, open Customize > Plugins, then the ... menu on DefenseClaw, and choose Remove. Until you remove the plugin, Cowork tool calls are blocked. uninstall --dry-run lists the step. See Remove the Cowork plugin.

When the sandbox teardown would run, uninstall and reset also stop before any change if DefenseClaw cannot read the sandbox list: the gateway or its sandbox daemon may be stopped, the list may time out, or its output may not be readable. The message says why. Run defenseclaw sandbox list to check; start the gateway first if it says to. For each copy-mode sandbox whose work you need, run defenseclaw sandbox pull NAME --apply (or --branch or --patch-out FILE) and confirm the project, branch or patch file contains it. Then stop the running sandboxes and retry, or use --stop-sandboxes to let teardown stop and delete any that still run. To leave sandboxes in place during uninstall, use --skip-sandbox-teardown. With sandboxes off, defenseclaw sandbox list fails whatever runs, so the message names defenseclaw-gateway sandbox teardown --dry-run instead, which lists them once OpenShell's gateway answers, and --skip-sandbox-teardown to uninstall without the teardown. The error, stopping, creating and deleting phases count as running. Only stopped, completed, deleted and missing do not.

Sandbox

Linux, and Apple-silicon Macs, where sandboxes are OpenShell MicroVMs that work on a copy (see macOS); Windows and WSL2 are not supported, and every sandbox command exits 3 there. 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. Every command and flag, with an example, is on Sandbox CLI; see also Sandbox.

CommandUse it for
defenseclaw sandbox setup [--harness H]... [--wrappers] [--non-interactive]One-time setup: checks the machine, installs OpenShell when you agree, enables project-folder mounts, records the harnesses, offers shell wrappers, and builds the harness images.
defenseclaw sandbox doctor [--fix] [--output json]Check that this machine can run sandboxes. defenseclaw doctor shows the same checks in its Sandbox section.
defenseclaw sandbox run <harness> [--copy] [--safe] [--profile open|balanced|strict] [-- args]Run a harness, such as claude or codex, in a new sandbox on the current folder.
defenseclaw sandbox list|status|connect|exec|logs|stop|start|deleteManage sandboxes and their sessions.
defenseclaw sandbox activity [-f]|approvals|approve|reject|unblockFollow the live activity feed, answer the rare asks, and lift egress blocks.
defenseclaw sandbox review|undo <name>Review a mounted project's changes or restore its pre-session snapshot.
defenseclaw sandbox pull <name> --applyBring a copy-mode sandbox's work into the project. --branch or --patch-out FILE preserves it elsewhere. A pull without a mode shows the review only.
defenseclaw sandbox policy show|explain|suggest|test|allow|blockShow where each setting of the sandbox policy comes from, suggest a pack from what sandboxes reached, test a destination, and edit the egress lists.
defenseclaw sandbox pack list|show|validateInspect sandbox policy packs and their digests.
defenseclaw sandbox image build|list|prune|rmBuild, list, prune, and remove the harness images.
defenseclaw sandbox enable|disable <harness>Add or remove the shell wrapper that makes a harness command run sandboxed.
defenseclaw sandbox teardown [--dry-run]Remove DefenseClaw's sandboxes, providers, images, gateway change, and wrappers. defenseclaw uninstall runs it.
defenseclaw sandbox kernel-feed install|status|uninstallLinux: install (as root), check or remove the opt-in sandbox kernel feed, a root service that adds Tetragon's exec and exit records to your docker sandboxes' process trees. Run as yourself, install prints the sudo command. See sandbox kernel-feed.

Enterprise

Commands for administrator-owned enterprise deployments. They are on the Go binary, which is not on the PATH: run it by its full path from the table below, as root on Linux and macOS and from an elevated prompt on Windows.

OSBinary
Linux/opt/defenseclaw/bin/defenseclaw-gateway
macOS/opt/cisco/defenseclaw/bin/defenseclaw-gateway
WindowsC:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe (the same Go binary under another name)

Standalone lifecycle on Linux and macOS

/opt/defenseclaw/bin/defenseclaw-gateway enterprise linux <action> (/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos <action> on macOS) 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.

On Linux tarball hosts with fapolicyd, trust the staged payload before ensure --no-start. After staging, add /opt/defenseclaw/ to the trust file for a fresh install or update its existing entry for an upgrade or rerun. Check the installed gateway as the service user before the final ensure. The tarball steps give the commands.

ActionUse it for
installInstall the deployment. Refuses when one is already installed
upgradeUpgrade an installed deployment from a new payload or package
repairRe-apply the installed deployment's files, modes, and services (restarts the services)
ensureInstall, upgrade, or repair as needed. Does nothing when nothing changed
reconcileRun one immediate hook guardian reconcile
rotate-credentialsReplace the key every user's per-user credentials derive from. Every user moves to the new key before it takes effect. See Rotate per-user credentials
statusReport the deployment state. Read-only
discoveryShow the AI Discovery inventory the hook guardian's per-user scans recorded for each enrolled account, then the runtime discovery planes and findings from the local gateway. Read-only; --user U limits it to one account, --json prints every record
profile-explainShow which guardrail profile a user, connector or agent gets, and why, with every configured profile's digest. Read-only; prints JSON. --user U (the account name as getent passwd prints it, uid, SID or principal; on a host with SSSD use_fully_qualified_names that is alice@corp.example.com, and the bare alice exits 1 with user lookup failed: no account named "alice" on this host and names the spelling to use), --connector C, --agent agt-.... See User- and group-based policies
agent-identitiesList the agent identities (agt-...) the gateway has seen, with their sessions, 1000 at a time. Read-only; prints JSON. --user U, --connector C, --cursor C (the previous page's next_cursor)
ide-pluginsList the IDE extensions and plugins of the last AI Discovery scan, per user. Read-only; prints JSON. --user U, --ide IDE, --ai-only, --cursor C (the previous page's next_cursor). See IDE plugin inventory
tetragon statusLinux. Report the kernel sensor and the DefenseClaw policies in it: Tetragon's version and socket check, the effective mode, the kernel_policy digest to put in enforce_ack, each policy's state, per-user burn-in and hits, agents observed but not enforced, your own Tetragon policies and their events, any pause or operator override, and orphaned names, then a Next: line. Reads the sensor helper's state files; root only. --user limits it to one account. --json follows a pinned schema. See Tetragon on a Linux fleet
tetragon verifyLinux. Check that this computer is ready for a Tetragon mode, one line per check with the command that fixes a failure. Without --ready-for it checks the configured mode. For enforce it also prints each user's burn-in progress and estimate, the details of every hit, and the enforce_ack block to approve. Exit 0 when no check fails, 1 when one fails (warnings never fail it), 2 for bad arguments. Never changes anything and never connects to Tetragon; root only. --json follows a pinned schema
tetragon pauseLinux. Move DefenseClaw's kernel controls to monitor mode until the pause ends. Survives restarts of the helper and of Tetragon. --for <duration> (default 4h, at most 7d), --until-reboot, --reason <text>. A runtime action, so it works on a managed computer
tetragon resumeLinux. End a pause; the next helper pass applies the configured intent
verifyCheck every file, permission, service, and readiness item. Read-only; exits non-zero on any problem
uninstallStop and remove the deployment and every account's hooks. Each account keeps ~/.defenseclaw and its sandboxes. When an account keeps sandboxes, the gateway's registration store (/var/lib/defenseclaw/sandbox on Linux or /opt/cisco/defenseclaw/runtime/sandbox on macOS) and key (/var/lib/defenseclaw/redaction-correlation.key or /opt/cisco/defenseclaw/runtime/redaction-correlation.key) stay root-owned while the service account is gone; the next ensure adopts them, with the root-only record of the sandbox setup they were made under. --purge removes them and each enrolled account's data and binaries for a clean image
FlagActionsMeaning
--payload <dir>install, upgrade, repair, ensureAbsolute directory that holds the staged binaries. Cannot be combined with --from-package
--from-packageinstall, upgrade, repair, ensureUse the binaries the defenseclaw-enterprise package installed
--config <file>install, upgrade, repair, ensureAbsolute path of the administrator config to install
--no-startinstall, upgrade, repair, ensureInstall without starting the services. Run repair or ensure to start them
--product-version <v>install, upgrade, repair, ensureRefuse unless the payload is exactly this version
--allow-downgradeinstall, upgrade, repair, ensureAllow a payload older than the installed release (a deliberate rollback). Without it the lifecycle refuses with downgrade_refused
--adopt-existinginstall, ensureBack up and take over an unmanaged DefenseClaw layout
--reason <text>ensure, tetragon pauseWhy ensure runs, or why kernel enforcement is paused. Recorded in the result
--for <duration>tetragon pauseHow long the pause lasts. Default 4h, at most 7d
--until-reboottetragon pauseKeep the pause in /run, so a reboot ends it. Not with --for
--lock-wait <duration>install, upgrade, repair, reconcile, rotate-credentials, ensure, uninstallWait up to this long (default 5s; 10m for ensure --reason path, as the apply trigger passes; at most 15m) for another lifecycle run before exiting 75
--purgeuninstallAlso remove each enrolled account's ~/.defenseclaw, the empty agent folders DefenseClaw created, its per-user binaries and launcher links in ~/.local/bin, and its uv cache entries, after stopping its per-user gateway and watchdog. An account's own earlier install (its ~/.defenseclaw has a config.yaml, .env, audit.db or previous) is left exactly as it is, with its binaries, and the result names the account (per_user_state_remaining). It also removes the sandbox registration store, key and setup record. Run it in the first removal: it needs the deployment's binaries. The result names each account it cleaned and each it left alone, with the reason. Without --purge, sandbox registrations and redaction-correlation.key may stay when an account keeps sandboxes.
--keep-stateuninstallKeep the config, credentials, gateway and guardian state (the sandbox registrations and key included), logs and the service account, so a reinstall resumes with them. The deployment record goes either way. Cannot combine with --purge
--keep-service-accountuninstallKeep the gateway service account, which uninstall deletes otherwise
--ready-for <mode>tetragon verifyThe mode to check readiness for: consume, observe or enforce
--user <u>discovery, profile-explain, agent-identities, ide-plugins, tetragon statusLimit the view to one account (name, uid or SID). A bare name lists the account of that name in every domain (profile-explain excepted: it resolves one account, so it needs the name getent passwd prints or the uid); a qualified name (alice@corp.example.com, CORP\alice) lists only the rows of exactly that domain (on Windows, whose rows keep the bare name next to the SID, every account of that name)
--connector <c>, --agent <id>profile-explain (--connector also agent-identities)The connector, or the agt- agent identity, to resolve or list
--ide <ide>, --ai-only, --cursor <c>ide-pluginsLimit to one IDE product or family, to AI plugins, or continue from the previous page
--jsonallPrint the lifecycle result as JSON

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

The sensor helper has two maintenance options for Tetragon, run as root:

sudo /opt/defenseclaw/bin/defenseclaw-sensor-helper --tetragon-cleanup
sudo /opt/defenseclaw/bin/defenseclaw-sensor-helper --tetragon-cleanup --check

--tetragon-cleanup deletes the Tetragon policies the helper recorded loading (only names that match defenseclaw-<family>-<8 hex> and are in its own state file) and empties that record. It exits 1, and removes nothing, while a helper in observe or enforce runs (stop it first: systemctl stop defenseclaw-sensor-helper), and 3 when Tetragon does not answer. --check only reports whether this helper supports the cleanup, with exit 0. uninstall, a rollback and the package's pre-removal script run it for you.

On an open-source Linux install the same binary is the sandbox kernel feed: defenseclaw-sensor-helper --sandbox-feed serves it (its systemd unit runs that), --sandbox-feed --check checks Tetragon and Docker and exits 0 or 1, and --sandbox-feed --uninstall removes the service and the root copy. Use defenseclaw sandbox kernel-feed rather than these.

Lifecycle on Windows

enterprise windows <action> manages the Windows deployment for both profiles. Run the installed CLI by its path from an elevated PowerShell prompt: for the standalone profile & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows <action>, and for the Secure Client profile & 'C:\Program Files\Cisco\Cisco Secure Client\DefenseClaw\bin\defenseclaw.exe' enterprise windows <action>. The standalone profile runs its transaction on PowerShell 7, which must be installed.

ActionProfilesUse it for
install, upgrade, repairSecure Client, standaloneInstall, upgrade, or re-apply the deployment
ensureStandalone onlyInstall, upgrade, or repair as needed. Refuses to downgrade (downgrade_refused)
reconcileSecure Client, standaloneRestart the guardian and wait for a fresh reconcile
status, verifySecure Client, standaloneRead-only state, and the full check
profile-explain, agent-identities, ide-pluginsStandaloneRead-only views of the managed gateway's guardrail profile resolution, agent identities and IDE plugin inventory, as JSON. Flags as on Linux and macOS: --user, --connector, --agent, --ide, --ai-only, --cursor
eventsStandaloneCheck the DefenseClaw event log entries (or, with --application, the Application log copies) against the lifecycle log; exits 1 on a forged entry or a missing record. --max N, --json. See Logs and events
uninstallSecure Client, standaloneRemove the services and every account's hooks. Standalone also removes the machine state; Secure Client keeps it unless --purge. Each account keeps %USERPROFILE%\.defenseclaw unless --purge
FlagMeaning
--profile secure_client|standaloneThe profile. Default: the supplied config's enterprise.profile, then the installed profile, then secure_client
--config <file>, --manifest <file>Administrator config and guardian target manifest (targets.yaml)
--trust-mode authenticode|hash_pinnedStandalone payload trust. Default at the CLI: authenticode
--payload-manifest <file>Standalone hash_pinned trust anchor: an administrator-owned JSON file of payload SHA-256 digests
--allowed-signer <sha256>Standalone: the SHA-256 thumbprint of an accepted Authenticode signer certificate. Repeatable
--product-version <v>Standalone: the version recorded for the deployment. Default: this CLI's version
--gateway-binary, --hook-binary, --hook-guard-binary, --acp-binary, --sensor-helper-binary, --cli-binarySource binaries for install, upgrade, repair, and ensure (--hook-guard-binary applies to the standalone profile only)
--broker-binarySecure Client only: the source credential broker
--installer <file>An explicit install-enterprise.ps1
--no-startInstall, upgrade, repair, ensure: stage the services disabled and stopped
--purgeUninstall: also remove managed state (Secure Client; standalone removes it without --purge) and (standalone) each enrolled account's %USERPROFILE%\.defenseclaw and DefenseClaw files in %USERPROFILE%\.local\bin, with that folder's user Path entry once it is empty. The result names each account. A signed-out account keeps its Path entry, and the result says so
--attest-claude-effective-policyInstall, upgrade, repair: record that an administrator confirmed that Claude Code runs DefenseClaw's managed hooks
--jsonPrint the result as JSON

Exit codes: standalone 0, 1603 failure, 1618 busy, 1639 invalid arguments, 5 when run from a standard account (status and verify need an elevated prompt; the JSON error code is elevation_required), 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.

ArgumentMeaning
/install, /upgrade, /repair, /reconcile, /status, /verify, /uninstall, /ensureThe action
CONFIG=<file>Absolute path of the config. A first /ensure needs it and exits 1639 without it
MANIFEST=<file>Absolute path of a guardian target manifest. /install needs both CONFIG= and MANIFEST=; /ensure prepares a manifest from the config
BUNDLE=<file>With /ensure on an installed computer: the signed policy bundle to apply. Not with CONFIG=
TRUSTANCHORS=<file>With /ensure: the administrator-only bundle trust anchor file to install first. Not with CONFIG=
DEVICEGROUP=<group>With TRUSTANCHORS=: pin the installed anchors to this one device group (--device-group)
REFUSECAPABILITYLOSS=1With /ensure and BUNDLE=: refuse a bundle that turns off an enforced capability
ALLOWEDSIGNERS=<sha256>,<sha256>Accepted Authenticode signer thumbprints, comma-separated
ATTESTCLAUDEEFFECTIVEPOLICY=1With /repair: record the Claude Code attestation
JSON=1, NOSTART=1, PURGE=1Print JSON, stage without starting, also remove each enrolled account's DefenseClaw data and per-user binaries on uninstall
FORCE=1With /uninstall, last resort: remove the deployment without recovering a pending transaction
TIMEOUTSECONDS=<n>Lifecycle timeout, from 60 to 7200 seconds, counted from when Setup starts. Default 1800. A change needs at least about 120; lower values suit only /verify and /status
/quiet, /norestartAccepted and ignored

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. Setup also exits 1639 for a CONFIG= or MANIFEST= file that a non-administrator owns or can change, and names the account and the icacls fix. A token that is not elevated exits 1603. The Secure Client Setup returns only 0 and 1603.

On managed Linux and macOS, an administrator's in-process scan code --json redacts its local output with a process-local key and leaves the gateway's audit store and correlation key alone. policy test reports nothing to run when the installed policy has no Rego tests.

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.

CommandUse it for
defenseclaw-gateway enterprise policy showShow each connector's route, lock, and coverage. --connector X limits it to one connector, --user NAME also checks that user's agent config, and --project DIR (with --user) also scans a project directory for foreign hooks
defenseclaw-gateway enterprise policy export --connector XPrint DefenseClaw's entries for your own policy tool. --format: codex takes toml or plist; claudecode takes json, claude-hklm-json, reg, plist, intune-settings-catalog, or version-floor (the version floor drop-in); cursor, copilot, and opencode take json. The default is the connector's native file
defenseclaw-gateway enterprise policy verifyVerify coverage. Exits 1 when it is incomplete. Takes the same --connector and --user flags. --live also runs the real client as the user; it needs --user, one --connector (codex or claudecode), and --agent-binary with an absolute path. --audit-db (the gateway audit database searched for the Claude Code check's tool call; default: the configured audit_db) and --timeout (default 90s) tune the live check

show and verify take --json. export prints the selected vendor format; it has no --json flag. On a standalone managed host, run the installed binary as root or from an elevated Windows prompt. The commands read the installed managed config and runtime automatically.

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise policy show --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise policy export --connector claudecode --format plist
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy show --json
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy export --connector codex --format toml

Protected credentials (enterprise secret)

CommandUse it for
defenseclaw-gateway enterprise secret set --name NStore a credential. Pass exactly one of --from-stdin or --from-file F. The value is never printed. On Linux and macOS, --lock-wait D (set and remove) waits up to D (at most 15m) for another lifecycle run instead of exiting 75
defenseclaw-gateway enterprise secret statusList stored credentials with a digest prefix and modification time, never the value
defenseclaw-gateway enterprise secret remove --name NRemove a credential. The MDM wrapper's put-back of a rotated credential (--undo-rotation with --undo-config SHA) works on Linux and macOS as well as Windows

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

DetailLinux and macOSWindows
After set or removeRuns ensure. set refuses before writing when the service account does not exist (nothing installed)Restarts the gateway
Requirementsroot for set and removeAn elevated prompt. set and remove also need an installed standalone deployment
Exit codes0, 1, 2, and 75 when the ensure it runs finds the lock held0, 1603, 1639 (invalid input)

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

Re-read directory facts (enterprise identity refresh)

/opt/defenseclaw/bin/defenseclaw-gateway enterprise identity refresh [--user U] [--flush-os-cache] [--max-users N] [--json] (/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS; & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' from an elevated PowerShell prompt on Windows) re-reads groups and UPN now, for one account or for every account the managed gateway has cached (default at most 500), and lists the accounts whose guardrail profile changed. Hook calls use the new facts from their next call. Root, or an elevated prompt or SYSTEM on Windows; anyone else gets not_admin. Standalone managed deployments only.

FlagEffect
--user UOnly this account (name, uid or SID)
--flush-os-cacheFirst flush the OS cache: Linux with SSSD sss_cache -u (with --user) or sss_cache -E; macOS dscacheutil -flushcache and dsmemberutil flushcache, without --user only (macOS has no per-account flush); Windows nothing
--max-users NRe-read at most N cached accounts (1 to 4096)

On Windows an account takes its groups from its sign-in token, so a signed-in account gets a directory group change at its next sign-in; the result lists it in windows_token_groups_pending. Account names appear only in the output; the audit row identity-refresh-completed and its telemetry carry counts. Exit codes: 0, 1 (1603), 2 (1639), 75 (1618) when another refresh is running. Schema: packaging/mdm/contract/identity-refresh.schema.json.

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.

CommandWho runs itUse it for
defenseclaw-gateway enterprise hooks statusAdministrator on Linux and macOS. On Windows, enterprise windows status runs itRead-only: the last guardian reconcile and the authorization ledger
defenseclaw-gateway enterprise hooks verifyAdministrator on Linux and macOS. On Windows, enterprise windows verify runs itRead-only: verify every enabled target in the manifest without repairing it
defenseclaw-gateway enterprise hooks watchGuardian serviceWatch the manifest's targets and repair them, with a periodic reconcile (--interval, default 1m)
defenseclaw-gateway enterprise hooks reconcileGuardian and lifecycleInstall or repair every enabled target once
defenseclaw-gateway enterprise hooks install, uninstallRoot or a guardian on Linux and macOS; only the guardian on WindowsInstall, repair, or remove one user's hook registration
defenseclaw-gateway enterprise hooks enumerateEnumerator service (Linux, macOS)Publish the target manifest. The Windows enumerator service runs enterprise windows enumerate of defenseclaw-gateway.exe
defenseclaw-gateway enterprise hooks scrubUninstall scripts, or an administratorRemove DefenseClaw's entries from one user's agent hook file (--connector, --file)

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 on Linux or macOS, use the same values as the guardian's unit or plist, and pass --manifest on macOS (/opt/cisco/defenseclaw/etc/hook-guardian/targets.yaml). On a managed Windows computer an elevated prompt has none of the service's settings, so enterprise hooks status and verify refuse and name enterprise windows status --profile standalone. Run enterprise windows status or verify instead: each runs the hooks command with the service's settings and includes its result.

On managed Windows, use an elevated PowerShell prompt and the lifecycle views, which include the guardian's health:

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

DEFENSECLAW_CONFIG alone does not provide the guardian's managed service pins and runtime identity to a direct enterprise hooks command. Windows hook mutations run only in the LocalSystem guardian.

ACP

In enterprise managed mode an administrator enrolls ACP (Agent Client Protocol) editors with /opt/defenseclaw/bin/defenseclaw-gateway enterprise acp enroll (/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS; preview, not yet verified live).

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.