CLI

Installation

Canonical package (Node.js):

npx veto-cli@latest <command>
pnpm dlx veto-cli@latest <command>
bunx veto-cli@latest <command>

Compatibility wrapper (kept for existing users):

npx veto-sdk@latest <command>

Python:

# Installed globally with pip
veto <command>

Commands

veto / veto studio / veto repl / veto --repl

Starts Veto Studio (full-screen, keyboard-first TUI) by default.

# No command defaults to Studio
veto

# Explicit Studio command
veto studio

# Compatibility entrypoints
veto repl
veto --repl

# Legacy line REPL
veto repl --legacy

Studio-focused flags:

• --renderer auto|ink|opentui|ansi
• --directory <path>
• --include-examples
• --include-tests
• --demo-template

Renderer notes:

• ink is the default interactive renderer on Node.js.
• opentui is optional and intended for Bun runtimes.
• ansi is fallback-safe for CI and limited terminals.
• if ink import/init fails at runtime, Studio falls back to ansi and prints a warning.

Legacy REPL (--legacy) keeps slash commands:

• /scan for coverage suggestions
• /test <tool>({args}) for local policy evaluation
• /test-suite for generated scenario testing
• /explain <ruleId> for rule explanations
• /export and /load for YAML workflows

For full workflows and a copy-paste demo script, see Interactive REPL.

veto policy generate

Generate policy YAML from natural language (local or cloud target).

# Local generation, save file
veto policy generate \
  --tool approve_invoice \
  --prompt "do not approve invoices above 50 dollars" \
  --save ./veto/rules/approve-invoice.yaml

# Cloud generation with machine-readable output
veto policy generate \
  --tool approve_invoice \
  --prompt "do not approve invoices above 50 dollars" \
  --target cloud \
  --json

veto policy apply

Apply an existing policy YAML file locally or submit it to cloud drafts.

veto policy apply --file ./veto/rules/approve-invoice.yaml
veto policy apply --file ./veto/rules/approve-invoice.yaml --target cloud --json

veto guard check

Run a non-interactive guard evaluation for a tool call.

# Explicit args JSON
veto guard check --tool approve_invoice --args '{"amount":120}' --mode local --json

# Pipe args from stdin
echo '{"amount":120}' | veto guard check --tool approve_invoice --mode local --json

veto cloud login and context commands

Device flow for human users and context management for CLI sessions.

veto cloud login
veto cloud whoami
veto cloud org use <org-id>
veto cloud project use <project-id>
veto cloud logout

Login flow:

1. Run veto cloud login in terminal.
2. Open the verification URL shown by CLI.
3. Approve the device code in dashboard.
4. Return to terminal; CLI stores scoped session tokens.

veto mcp serve / veto mcp doctor / veto mcp init

Run Veto as an MCP gateway in self-hosted environments.

# Scaffold config
veto mcp init

# Validate connectivity and config
veto mcp doctor
veto mcp doctor --json

# Start gateway
veto mcp serve --config ./veto/mcp.config.yaml

Quick one-off serve without a config file:

veto mcp serve \
  --upstream http://localhost:3000/mcp \
  --api-key veto_xxx \
  --policy-server http://localhost:3001

Flags:

• --config <path> for serve/doctor
• --listen <host:port> for serve
• --upstream <url> and --transport <mcp-sse|mcp-stdio> for quick serve
• --api-key <key> and --policy-server <url> for policy checks
• --timeout-ms <n> for upstream timeout
• --json for deterministic command output (doctor, init, and startup envelope on serve)

Managed/runtime support notes:

• managed cloud MCP gateway supports mcp-sse
• self-hosted CLI gateway supports mcp-sse and mcp-stdio

For managed APIs and architecture details, see MCP Gateway guide.

veto doctor

Diagnostics for runtime, renderer, auth, and connectivity:

veto doctor
veto doctor --json

Runtime troubleshooting

If npx veto-cli@latest fails with module-resolution errors from ~/.npm/_npx, it is usually a corrupted transient npx install cache, not a policy/runtime bug.

Use either approach:

# One-off isolated cache
npm_config_cache=/tmp/veto-npx-cache npx -y veto-cli@latest

# Then retry normal invocation
npx -y veto-cli@latest

For renderer diagnostics:

veto doctor --json

veto init

Scaffolds a new Veto configuration in the current directory.

npx veto init
npx veto init --force    # Overwrite existing files
npx veto init --pack coding-agent

Creates:

veto/
├── veto.config.yaml    # Main configuration file
└── rules/
    └── defaults.yaml   # Default rule template

The generated veto.config.yaml defaults to local mode:

version: "1.0"
mode: "strict"

No API key or account needed to start. Add VETO_API_KEY to switch to cloud mode later.

If the veto/ directory already exists, the command does not overwrite existing files unless --force is set.

--pack pre-fills veto/rules/defaults.yaml with:

version: "1.0"
extends: "@veto/<pack>"

Supported built-in packs:

• coding-agent
• financial
• browser-automation
• data-access

You can pass either coding-agent or @veto/coding-agent.

veto compile

Compiles natural language policy descriptions into deterministic YAML rules using an LLM at build time.

# From inline text
veto compile --input "Block emails to domains outside company.com" --output ./veto/rules/email.yaml

# From a text file
veto compile --file policies.txt --output ./veto/rules/

# With a specific provider
veto compile --input "Cap transfers at $5000" --output ./veto/rules/limits.yaml --provider anthropic

The compile command uses the LLM only at build time. The generated YAML rules run locally with zero network calls at runtime.

Requires the corresponding provider API key as an environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY).

veto learn

Observe tool calls and auto-generate tight allowlist policies from real usage patterns.

# Stop after 10 tool calls
veto learn --runs 10

# Stop after 30 minutes
veto learn --duration 30m

# Custom output path
veto learn --output ./veto/rules/learned.yaml

The learn command reads tool calls from stdin as JSON objects, one per line:

{"tool": "send_email", "args": {"to": "alice@company.com", "subject": "Hello"}}
{"tool": "transfer_funds", "args": {"amount": 500, "currency": "USD"}}

After observing enough calls, it generates deterministic constraints:

• Number ranges with configurable margin
• String enum allowlists (when fewer than 10 unique values observed)
• Required field detection
• Array length bounds

veto test

Adversarial policy gap finder. Analyzes your YAML rules for coverage gaps, regex bypasses, type coercion issues, and uncovered tools.

# Analyze default policy directory
veto test

# Analyze specific directory
veto test --policy ./veto/rules

# Save JSON report
veto test --output report.json

# JSON output format
veto test --format json

Exit codes:

• 0 — No critical gaps found
• 1 — Critical gaps detected (CI-friendly)

Gap severities:

veto scan

Audits discovered tools in your project against loaded rule coverage.

# Audit current project
veto scan

# Include inline YAML starter snippets for uncovered tools
veto scan --suggest

# Fail CI if uncovered tools exist
veto scan --fail-uncovered

# Machine-readable output
veto scan --format json

Coverage behavior:

• A tool is covered if at least one matching tool rule exists, or at least one global rule is present.

Exit codes:

• 0 — Scan executed successfully
• 1 — Only when --fail-uncovered is set and uncovered tools were found

veto diff

Compares policy snapshots and can replay deterministic impact against historical tool-call logs.

# Compare working file vs HEAD snapshot (git-aware mode)
veto diff financial.yaml

# Compare explicit file or directory snapshots
veto diff --old ./rules-v1 --new ./rules-v2

# Add deterministic impact replay from JSONL tool-call log
veto diff financial.yaml --log calls.jsonl

# JSON output
veto diff --old ./rules-v1 --new ./rules-v2 --log calls.jsonl --format json

Invocation modes:

• Positional mode: veto diff <policy-path> compares working copy vs HEAD for that path.
• Explicit mode: --old and --new must both be provided, and both must be files or both directories.

veto version

Prints the current SDK version.

npx veto version
# veto v<installed-version>

veto help

Shows all commands and flags.

npx veto help