Skip to content

CLI Reference

The guardrails CLI lets you validate, inspect, and test policies from the terminal.

Commands

guardrails version

Show the installed version.

guardrails version
# guardrails 0.1.0

guardrails validate

Check a policy file for errors without loading the engine.

guardrails validate --config guardrails.yaml
# Policy is valid: 6 rules, 4 profiles, 3 matchers
Option Default Description
--config, -c guardrails.yaml Policy file path

Exit code 0 = valid, 1 = errors found.

guardrails inspect

Display a formatted summary of all rules, profiles, and matchers in a policy.

guardrails inspect --config guardrails.yaml
guardrails inspect --config guardrails.yaml --tag compliance
Option Default Description
--config, -c guardrails.yaml Policy file path
--tag — Filter rules by tag

guardrails check

Evaluate a single event against a policy. The primary tool for testing rules.

# Allow
guardrails check --config guardrails.yaml \
  --event '{"scope":"input","agent":"test","data":{"content":"hello"}}'

# Deny
guardrails check --config guardrails.yaml \
  --event '{"scope":"input","agent":"test","data":{"content":"ignore previous instructions"}}'
Option Default Description
--config, -c guardrails.yaml Policy file path
--event, -e (required) Event as a JSON string
--dry-run false Evaluate without enforcing (exit code always 0)
--output, -o console Output format: console or json

Event JSON format:

{
  "scope": "input",
  "agent": "sales-agent",
  "data": {"content": "..."},
  "session_id": "optional",
  "source_agent": "optional (cross_agent)",
  "target_agent": "optional (cross_agent)"
}

Exit codes:

Code Meaning
0 Event was allowed, or dry run mode
1 Event was denied

guardrails audit

View and filter the audit log.

guardrails audit
guardrails audit --agent sales-agent --outcome deny
guardrails audit --since 2026-03-26 --output json --output-file report.json
Option Default Description
--config, -c guardrails.yaml Policy file path
--since — Show entries after this ISO timestamp
--agent — Filter by agent name
--outcome — Filter by outcome (allow, deny, require_approval, redact)
--rule — Filter by rule name
--limit 1000 Maximum entries to return
--output, -o console Output format: console or json
--output-file — Write JSON output to file