Commands

Warden’s command surface is intentionally small. Most of the work happens automatically via hooks.

Core Commands

warden init

Interactive setup wizard. Creates ~/.warden/, installs the binary to PATH, detects missing CLI tools (rg, fd, bat, etc.) and offers to install them, configures hooks for your AI assistant, writes default config, and starts the daemon.

warden init

If you’ve already run init, it detects the existing installation and skips completed steps.

warden install <agent>

Configure hooks for a specific AI assistant. This is the targeted version of init — it only sets up hooks, not the full directory structure.

warden install claude-code
warden install gemini-cli

If hooks are already installed, it warns you and suggests warden update instead.

warden uninstall

Remove hooks from the AI assistant, stop the daemon, and optionally delete all Warden data.

warden uninstall

You’ll be asked whether to delete ~/.warden/ and all session data. If you decline, the data is preserved for potential re-installation.

warden update

Check for new versions and optionally apply updates.

# Check for updates (default)
warden update
warden update --check

# Download and apply the update
warden update --apply

--check queries GitHub Releases for the latest version and compares it to your installed version. --apply downloads the new binary and replaces the current one. Configuration and session data are preserved.

warden config

View or modify runtime configuration.

# Show the config file path
warden config path

# Print the current config
warden config list

# Get a specific value
warden config get telemetry.drift_velocity

# Set a value
warden config set telemetry.drift_velocity false

# Output JSON Schema for config.toml validation
warden config schema

warden describe

Show all active rules, their IDs, categories, severities, and whether they can be disabled.

# Show active rules
warden describe

# Show ALL rules including compiled defaults
warden describe --all

The output includes the rule ID (e.g., safety.0), category (Safety, Substitution, Hallucination, etc.), severity (HardDeny, SoftDeny, Advisory), and the pattern and message.

warden doctor

Run a health check on your Warden installation.

warden doctor

Checks that:

• The binary is on PATH and executable
• The daemon is running and reachable
• Hook scripts are registered with your AI assistant
• Required CLI tools are installed
• Config files parse correctly
• The redb database is accessible

warden version

Print the installed version.

warden version

Clean Command Aliases

The following commands are clean aliases for their debug- prefixed counterparts. Both forms work — the clean names are preferred, and the debug- prefix is kept for backward compatibility.

Usage examples

# See why the grep substitution rule exists
warden explain substitution.0

# Review the last session's quality metrics
warden scorecard

# Export session data for analysis
warden export > session.json

# Check daemon health
warden daemon-status

# Launch the live dashboard
warden tui

MCP Server

Warden includes a built-in MCP (Model Context Protocol) server — a bidirectional channel that lets AI agents query Warden’s state programmatically. Start it with warden mcp.

Hooks vs MCP: Hooks are automatic — they fire on every tool call without agent action. MCP is on-demand — the agent explicitly queries Warden when it needs guidance. Most sessions run entirely on hooks. MCP shines when the agent wants to self-correct or when building custom integrations.

MCP Tools

JSON-RPC Examples

suggest_action — Get a context-aware recommendation:

// Request
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "suggest_action", "arguments": {}}}

// Response
{"jsonrpc": "2.0", "id": 1,
 "result": {"content": [{"type": "text", "text":
   "{\"action\": \"run verification\",
     \"reason\": \"4 files edited since last build\",
     \"confidence\": 0.85}"}]}}

session_status — Check session health:

// Request
{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
 "params": {"name": "session_status", "arguments": {}}}

// Response
{"jsonrpc": "2.0", "id": 2,
 "result": {"content": [{"type": "text", "text":
   "{\"phase\": \"Productive\",
     \"turn\": 24,
     \"focus_score\": 82,
     \"trust_score\": 91,
     \"verification_debt\": 2,
     \"loop_detected\": false}"}]}}

explain_denial — Understand why something was blocked:

// Request
{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
 "params": {"name": "explain_denial", "arguments": {"rule_id": "safety.3"}}}

// Response
{"jsonrpc": "2.0", "id": 3,
 "result": {"content": [{"type": "text", "text":
   "{\"id\": \"safety.3\",
     \"category\": \"Safety\",
     \"severity\": \"HardDeny\",
     \"pattern\": \"\\\\bsudo\\\\s\",
     \"message\": \"BLOCKED: sudo is not allowed. Run without sudo.\",
     \"times_fired\": 12}"}]}}

check_file — Check a file’s relevance and history:

// Request
{"jsonrpc": "2.0", "id": 4, "method": "tools/call",
 "params": {"name": "check_file", "arguments": {"path": "src/handlers/auth.rs"}}}

// Response
{"jsonrpc": "2.0", "id": 4,
 "result": {"content": [{"type": "text", "text":
   "{\"in_working_set\": true,
     \"edit_count\": 3,
     \"last_edited_turn\": 18,
     \"issues\": []}"}]}}