CLI Reference
Full documentation for all AgentWard commands, the policy YAML format, and troubleshooting guide.
Get started in 30 seconds.
pip install agentward
Requires Python 3.11+. No API key. Everything runs locally. Mac and Linux supported.
agentward init
The recommended way to start. Runs the full pipeline interactively in one command: scan → configure → setup → inspect. Discovers your tools, shows a risk summary, generates a policy, wires enforcement into your agent host, and starts the proxy — all in ~10 seconds.
agentward init
Static analysis of all tool sources. Auto-discovers MCP configs, scans Python source files, and queries live MCP servers via subprocess + JSON-RPC handshake. Outputs a risk-rated permission map with use-case-aware recommendations.
agentward scan # auto-discover all sources agentward scan ~/.cursor/mcp.json # scan specific MCP config agentward scan ~/project/ # scan directory (MCP + Python + OpenClaw) agentward scan --json > report.json # machine-readable output agentward scan --format html # shareable HTML report with score badge agentward scan --ci --format sarif # SARIF for GitHub Security tab
| OPTION | DESCRIPTION |
|---|---|
| --json | Raw JSON output for piping into other tools |
| --format html | Shareable HTML report with risk score badge |
| --format sarif | SARIF output for GitHub Security tab integration |
| --ci | CI mode — exit code 1 if CRITICAL risks found |
| --timeout N | MCP server enumeration timeout in seconds (default: 15) |
Generates a smart-default agentward.yaml policy file based on scan results and detected use-case patterns. Runs the full scan pipeline internally, then produces security-aware defaults tailored to what's actually installed.
agentward configure # auto-discover and generate agentward configure ~/clawd/skills/ # generate from OpenClaw skills dir agentward configure -o my-policy.yaml # custom output path
| OPTION | DESCRIPTION |
|---|---|
| -o / --output PATH | Output path for generated policy (default: ./agentward.yaml) |
| --timeout N | MCP server enumeration timeout in seconds |
Wires AgentWard enforcement into your existing tool infrastructure. Two modes: MCP mode rewrites server commands in agent host config files; Gateway mode swaps the ClawdBot port so AgentWard sits as an HTTP reverse proxy.
agentward setup --policy agentward.yaml # wrap all discovered MCP configs agentward setup --config ~/.cursor/mcp.json # wrap specific config file agentward setup --gateway clawdbot # swap ClawdBot gateway port agentward setup --gateway clawdbot --undo # restore original port agentward setup --dry-run --policy agentward.yaml # preview changes only
| OPTION | DESCRIPTION |
|---|---|
| -c / --config PATH | Target a specific MCP config file |
| -p / --policy PATH | Policy file to enforce (default: ./agentward.yaml) |
| -l / --log PATH | Audit log file path |
| --undo | Restore original configuration |
| --dry-run | Preview changes without writing files |
| -g / --gateway NAME | Gateway mode — supports: clawdbot |
Starts the runtime proxy with live policy enforcement. Stdio mode runs as an MCP proxy between agent host and server subprocess. HTTP mode runs as a reverse proxy between clients and the ClawdBot gateway.
agentward inspect --policy agentward.yaml -- npx server # stdio proxy agentward inspect --gateway clawdbot --policy agentward.yaml # HTTP proxy agentward inspect -- npx server # passthrough (logging only) agentward inspect --policy agentward.yaml --dry-run -- npx s # observe without blocking
| OPTION | DESCRIPTION |
|---|---|
| -p / --policy PATH | Policy file to enforce |
| -l / --log PATH | Audit log file path (JSON Lines format) |
| -g / --gateway NAME | HTTP gateway mode — supports: clawdbot |
| --dry-run | Observe-only: log what would be blocked without blocking |
Evaluates current policy against regulatory frameworks and generates compliance delta reports with specific gaps and auto-fix suggestions. With --fix, generates a corrected policy file with all required changes applied.
agentward comply --framework hipaa # compliance delta report agentward comply --framework sox --fix # auto-generate SOX-compliant config agentward comply --framework gdpr --json # JSON output for CI agentward comply --framework pci-dss --policy custom.yaml # custom policy path
| OPTION | DESCRIPTION |
|---|---|
| -f / --framework NAME | Compliance framework: hipaa (default) · sox · gdpr · pci-dss |
| --fix | Generate a corrected policy file with all required changes |
| -p / --policy PATH | Policy file to evaluate (default: ./agentward.yaml) |
| -o / --output PATH | Output path for fixed policy file |
| --json | Machine-readable JSON output |
HIPAA — Security Rule (8 controls)
- Access Control §164.312(a)(1) — PHI skill-level access restrictions
- Data Boundary §164.312(a)(1) — PHI containment within designated zones
- Audit Controls §164.312(b) — structured audit trail with SSN detection
- Integrity §164.312(c)(1) — data modification controls for PHI skills
- Authentication §164.312(d) — identity verification gates for PHI write/send/delete
- Transmission Security §164.312(e)(1) — outbound network controls for PHI skills
- Information Access Management §164.308(a)(4) — least-privilege via chaining isolation
- Zero-Trust Default — best practice:
default_action: block
SOX — Section 404 (8 controls)
- Access Control §404 — financial skill-level access restrictions
- Data Boundary §404 — financial data containment within designated zones
- Audit Trail §404 — sensitive content scanning with credit card detection
- Integrity Controls §404 — write restrictions for financial skills
- Authorization Controls §404 — human approval for financial write/send/delete
- Network Segregation §404 — outbound network controls for financial skills
- Segregation of Duties §404 — financial skill isolation via chaining rules
- Zero-Trust Default — best practice:
default_action: block
GDPR — Key Articles (8 controls)
- Data Minimisation Art. 5(1)(c) — personal data skill-level access restrictions
- Data Protection by Design Art. 25 — personal data boundary zones with blocking
- Records of Processing Art. 30 — sensitive content scanning for audit trail
- Integrity of Processing Art. 32(1) — write restrictions for personal data skills
- Confidentiality of Processing Art. 32(1) — human approval for write/send/delete
- Transmission Security Art. 32(1) — outbound network controls for personal data
- Processor Obligations Art. 28 — personal data skill isolation via chaining rules
- Accountability Default Art. 5(2) — best practice:
default_action: block
PCI-DSS v4.0 — Key Requirements (8 controls)
- Restrict Access Req. 7 — cardholder data skill-level access restrictions
- Cardholder Data Environment Req. 7 — CDE boundary zones with blocking
- Log and Monitor Req. 10 — sensitive content scanning with credit card + CVV detection
- Protect Stored Data Req. 3 — write restrictions for cardholder data skills
- Identify and Authenticate Req. 8 — human approval for cardholder write/send/delete
- Network Segmentation Req. 1 — outbound network controls for cardholder data
- Least Privilege Isolation Req. 7 — cardholder data skill isolation via chaining
- Secure Default Req. 6 — best practice:
default_action: block
Policy YAML Format
The agentward.yaml file is the single source of truth for all enforcement rules. It's framework-agnostic — the same file is used by both the stdio proxy and the HTTP proxy.
ClawdBot Gateway
Correct restart command for ClawdBot
ClawdBot does NOT support clawdbot stop, clawdbot start, or clawdbot restart as standalone commands. The correct command is:
clawdbot gateway restart
Also avoid clawdbot reset — that cancels the current operation, it does not restart the gateway.
"Address already in use" (OSError Errno 48) on port 18789
Symptom: AgentWard proxy fails to start with OSError: [Errno 48] address already in use on port 18789.
Root cause: ClawdBot is still listening on port 18789 because it wasn't restarted after agentward setup --gateway clawdbot swapped the port.
Fix:
agentward setup --gateway clawdbot # if not done yet clawdbot gateway restart # move ClawdBot to new port lsof -i :18790 # verify: should show node lsof -i :18789 # verify: should be empty agentward inspect --gateway clawdbot --policy agentward.yaml
ClawdBot still binds old port after config edit
Symptom: After editing clawdbot.json to change the port, ClawdBot still binds to the old port after restart.
Root cause: ClawdBot uses a macOS LaunchAgent plist at ~/Library/LaunchAgents/com.clawdbot.gateway.plist that hardcodes the port in TWO places — ProgramArguments and EnvironmentVariables. ClawdBot reads from the plist at launch, not from clawdbot.json.
Fix: Run agentward setup --gateway clawdbot — it patches both files automatically. If debugging manually, check both clawdbot.json and the plist.
Proxy starts but forwards to itself (infinite loop)
Root cause: A stale .agentward-gateway.json sidecar file from a previous run.
Fix:
rm ~/.clawdbot/.agentward-gateway.json agentward setup --gateway clawdbot clawdbot gateway restart agentward inspect --gateway clawdbot --policy agentward.yaml
ClawdBot UI blank / connection error through proxy
Root cause (historical): The HTTP proxy was not forwarding WebSocket upgrade requests. ClawdBot's React SPA communicates with the gateway over WebSocket.
Current state: Fixed. The proxy now detects WebSocket upgrade headers (Upgrade: websocket + Connection: upgrade) and proxies WebSocket traffic bidirectionally. No action needed unless you see this after code changes.
Policy enforcement not triggering on tool calls
ClawdBot's tool invocation endpoint is POST /tools-invoke (with a hyphen), NOT /tools/invoke (with a slash). If policy enforcement isn't triggering, verify the proxy is intercepting the correct path.
HTTP Proxy
"Error handling request from 127.0.0.1"
Root cause (historical): Two bugs: request.json() consumed the body then request.read() returned empty bytes when forwarding; and web.StreamResponse with copied Content-Length header caused mismatches.
Current state: Fixed. Proxy reads raw body once with request.read(), parses with json.loads(), passes cached raw_body to _forward_request(). Uses web.Response (not StreamResponse).
MCP Stdio Proxy
Server subprocess exits immediately
Test the server command standalone first:
npx -y @modelcontextprotocol/server-filesystem /tmp
If it requires specific env vars or paths, pass them through the agentward command. AgentWard inherits the calling environment.
Agent stopped using a tool after I re-enabled it in policy
Symptom: You blocked a tool, then removed the block from agentward.yaml and restarted the proxy. The agent still avoids using the tool.
Root cause: Not AgentWard. When a tool is blocked, AgentWard injects a message like [AgentWard: blocked tool 'browser'] into the LLM response. The LLM sees this in its conversation history and "remembers" the restriction — so even after you re-enable it, the LLM avoids the tool because it thinks it's still blocked.
Fix: Start a new chat session after changing your policy. A fresh conversation has no memory of the previous block. Confirm AgentWard is not blocking by checking proxy output — if you see ALLOW, the tool is allowed through.