CLI Reference¶

SafeAI ships a single safeai command with subcommands for scanning, serving, auditing, and managing your safety configuration.

uv pip install safeai
safeai --help

safeai init¶

Scaffold SafeAI configuration files and interactively configure the intelligence layer.

safeai init [--path DIR] [--non-interactive]

Flags¶

What it does¶

1. Scaffolds config files — creates default policies, contracts, schemas, and agent identities
2. Interactive intelligence setup — walks you through choosing an AI backend (Ollama, OpenAI, Anthropic, or custom) and writes the configuration to safeai.yaml

This creates:

Example¶

$ safeai init
SafeAI initialized
  created: safeai.yaml
  created: policies/default.yaml
  ...

Intelligence Layer Setup
SafeAI can use an AI backend to auto-generate policies,
explain incidents, and recommend improvements.

Enable the intelligence layer? [Y/n]: Y

Choose your AI backend:
  1. Ollama (local, free — no API key needed)
  2. OpenAI
  3. Anthropic
  4. Google Gemini
  5. Mistral
  6. Groq
  7. Azure OpenAI
  8. Cohere
  9. Together AI
  10. Fireworks AI
  11. DeepSeek
  12. Other (any OpenAI-compatible endpoint)

Select provider [1]: 1

Intelligence layer configured!
  provider: ollama
  model:    llama3.2

safeai scan¶

Scan text through the SafeAI boundary engine and return the enforcement decision.

safeai scan --boundary <BOUNDARY> --input <TEXT>

Flags¶

Examples¶

# Scan an input prompt for secrets and PII
safeai scan --boundary input --input "My SSN is 123-45-6789"

# Scan model output before returning to a user
safeai scan --boundary output --input "Here is the API key: sk-abc123..."

The command prints the enforcement result (allow, block, redact, or flag) along with any matched detections.

safeai validate¶

Validate your SafeAI configuration files: policies, schemas, memory definitions, and agent identity documents.

safeai validate --config <PATH>

Flags¶

Examples¶

# Validate the default config
safeai validate

# Validate a specific config file
safeai validate --config /etc/safeai/production.yaml

Output includes counts of policies loaded, memory schemas validated, and agent identity documents found.

safeai logs¶

Query the audit log for boundary enforcement decisions.

safeai logs [FLAGS]

Flags¶

Examples¶

# Last 20 events, JSON output
safeai logs

# Last 10 block decisions in the past hour, plain text
safeai logs --tail 10 --action block --last 1h --text-output

# Filter by agent and boundary
safeai logs --agent research-agent --boundary input --tail 50

# Full detail for a specific event
safeai logs --detail evt_a1b2c3d4

safeai serve¶

Start the SafeAI proxy server in sidecar or gateway mode.

safeai serve [FLAGS]

Flags¶

Modes¶

• Sidecar -- Runs alongside a single agent process. All traffic from that agent passes through SafeAI for scanning and enforcement.
• Gateway -- Sits between multiple agents and upstream services. Requires source/destination agent context on each request for multi-agent enforcement.

Examples¶

# Start a sidecar on the default port
safeai serve

# Start a gateway on port 9000 with a custom config
safeai serve --mode gateway --port 9000 --config /etc/safeai/prod.yaml

safeai hook¶

Universal coding-agent hook. This command reads a pending tool call from stdin, enforces SafeAI policies, and returns the decision.

safeai hook

The hook is designed to be called by coding agents (Claude Code, Cursor, etc.) as a pre-execution gate. It:

1. Reads the tool name and arguments from stdin (JSON).
2. Loads the agent profile for the calling agent.
3. Evaluates the action against configured policies and tool contracts.
4. Returns allow, block, or require_approval with an explanation.

safeai setup¶

Install SafeAI hooks into a supported coding agent.

safeai setup <AGENT>

Supported agents¶

Examples¶

# Install the hook for Claude Code
safeai setup claude-code

# Install the hook for Cursor
safeai setup cursor

The installer registers safeai hook as the pre-execution callback in the agent's configuration, so every tool invocation is evaluated by SafeAI before execution.

safeai approvals¶

Manage the human-in-the-loop approval workflow for actions that require explicit authorization.

safeai approvals <SUBCOMMAND> [FLAGS]

Subcommands¶

Examples¶

# List all pending approvals
safeai approvals list

# Approve a specific request
safeai approvals approve req_abc123

# Deny a specific request with a reason
safeai approvals deny req_def456 --reason "Outside permitted scope"

safeai templates¶

Browse and inspect the built-in policy template catalog.

safeai templates <SUBCOMMAND>

Subcommands¶

Examples¶

# List all templates (built-in + plugins)
safeai templates list

# Show the healthcare template pack
safeai templates show healthcare

# Show the finance template
safeai templates show finance

Built-in template packs include finance, healthcare, and support. Plugin-provided templates are discovered automatically when plugins are loaded.

safeai mcp¶

Start the SafeAI MCP (Model Context Protocol) server for tool-based integration with MCP-compatible clients.

safeai mcp

The MCP server exposes SafeAI's scanning, policy evaluation, and audit capabilities as MCP tools, allowing MCP-compatible agents and IDEs to call SafeAI directly through the protocol.

safeai intelligence¶

AI advisory commands for configuration generation, policy recommendations, incident explanation, compliance mapping, and integration code generation.

safeai intelligence <SUBCOMMAND> [FLAGS]

Subcommands¶

auto-config¶

safeai intelligence auto-config [--path .] [--framework langchain] [--output-dir .safeai-generated] [--apply] [--config safeai.yaml]

recommend¶

safeai intelligence recommend [--since 7d] [--output-dir .safeai-generated] [--config safeai.yaml]

explain¶

safeai intelligence explain <EVENT_ID> [--config safeai.yaml]

Takes a single event ID as argument and prints the classification and explanation.

compliance¶

safeai intelligence compliance --framework <FRAMEWORK> [--output-dir .safeai-generated] [--config safeai.yaml]

integrate¶

safeai intelligence integrate --target <FRAMEWORK> [--path .] [--output-dir .safeai-generated] [--config safeai.yaml]

safeai alerts¶

Manage alert channels for enforcement event notifications.

safeai alerts <SUBCOMMAND> [FLAGS]

Subcommands¶

Examples¶

# Add a Slack webhook channel
safeai alerts add --channel slack --url https://hooks.slack.com/services/...

# Add a file-based alert log
safeai alerts add --channel file --path /var/log/safeai/alerts.json

# Add a generic webhook
safeai alerts add --channel webhook --url https://example.com/alerts

# List all configured channels
safeai alerts list

# Send a test alert
safeai alerts test --channel slack

safeai observe¶

Observe agent activity and session traces.

safeai observe <SUBCOMMAND>

Subcommands¶

Examples¶

# View agent activity across all agents
safeai observe agents

# View session traces
safeai observe sessions

safeai skills¶

Manage installable SafeAI skill packages. Skills bundle policies, plugins, deployment scripts, and reference documentation into reusable packages.

safeai skills <SUBCOMMAND> [FLAGS]

Subcommands¶

Examples¶

# List all installed skills
safeai skills list

# Search for skills by keyword
safeai skills search secret
safeai skills search gdpr

# Install a skill from the registry
safeai skills add prompt-injection-shield
safeai skills add gdpr-policies

# Remove an installed skill
safeai skills remove prompt-injection-shield

Available Skills¶