Skip to main content

​
Overview

The main warden command analyzes your code for issues using skills defined in warden.toml.

​
Usage

warden [targets...] [options]

​
Targets

Specify what code to analyze. Defaults to uncommitted changes if no targets provided.

​
Uncommitted changes (default)

warden
Analyzes:
  • Unstaged changes (modified files)
  • Staged changes (files added to git)

​
Specific files

warden src/api/users.ts
warden src/api/users.ts src/utils/auth.ts

​
Directories

warden src/api/
warden src/ test/

​
Git diffs

# Compare with branch
warden main..HEAD
warden origin/main..feature-branch

# Compare commits
warden abc1234..def5678

​
Glob patterns

warden 'src/**/*.ts'
warden '*.{ts,tsx}'
Quote glob patterns to prevent shell expansion.

​
Options

​
Analysis Control

​
—config, -c

Use a custom configuration file: 
warden --config ./configs/strict.toml
Default: warden.toml in repo root.

​
—skill

Run a specific skill only: 
warden --skill find-bugs
Skill name from warden.toml.

​
—fail-on

Minimum severity to exit with failure code: 
warden --fail-on high
warden --fail-on medium
warden --fail-on off  # Never fail
Values: off, high, medium, low

​
—report-on

Minimum severity to show in output: 
warden --report-on medium
warden --report-on low
Values: off, high, medium, low

​
—min-confidence

Minimum confidence level to show in output: 
warden --min-confidence high
warden --min-confidence medium
Values: off, high, medium, low Default: medium

​
—max-findings

Limit number of findings reported: 
warden --max-findings 10

​
Output Control

​
—quiet, -q

Minimal output - only errors: 
warden --quiet

​
—verbose

Show detailed progress: 
warden --verbose

​
—debug

Show debug information: 
warden --debug

​
—json

Output findings as JSON: 
warden --json > findings.json

​
—output, -o

Write findings to JSONL file: 
warden --output findings.jsonl

​
—no-color

Disable colored output: 
warden --no-color

​
Performance

​
—parallel, -p

Number of concurrent skill executions: 
warden --parallel 3
Default: 4

​
—fail-fast, -x

Stop after first finding: 
warden --fail-fast
Useful for quick checks or CI pipelines.

​
—staged

Analyze only staged changes (git diff —cached): 
warden --staged

​
—git

Force ambiguous targets to be treated as git refs: 
warden --git feature

​
—offline

Use cached remote skills without network access: 
warden --offline
Useful for offline development or air-gapped environments.

​
—model, -m

Override model for all skills: 
warden --model claude-sonnet-4-20250514
Fallback when not set in config.

​
Other

​
—help, -h

Show help: 
warden --help

​
—version, -v

Show version: 
warden --version

​
Exit Codes

CodeMeaning
0Success - no failures above threshold
1Failure - findings exceed failOn threshold
130User aborted (Ctrl+C)

​
Examples

​
Analyze uncommitted changes

npx warden
Output: 
⚡ Warden v0.18.0

🔍 Running 2 skills on 5 files...

✓ code-quality: 3 findings
  src/api/users.ts:45 - Missing error handling [medium]
  src/api/auth.ts:12 - Hardcoded secret [high]
  src/utils/jwt.ts:89 - Weak signature algorithm [high]

✓ security-audit: 1 finding
  src/api/auth.ts:12 - Credentials in code [high]

💰 Cost: $0.05 (18.2K tokens)

❌ Failed: 3 high severity findings (threshold: high)

​
Analyze specific directory

npx warden src/api/

​
Compare with main branch

npx warden main..HEAD

​
Quiet mode for CI

if npx warden --quiet; then
  echo "✓ Passed"
else
  echo "✗ Failed"
  exit 1
fi

​
JSON output

npx warden --json > findings.json
cat findings.json | jq '.findings[] | select(.severity == "high")'

​
Verbose output

npx warden --verbose
Output: 
⚡ Warden v0.18.0

📁 Discovered 2 skills
  • code-quality (local)
  • security-audit (remote: getsentry/skills@abc1234)

🔍 Running 2 skills on 5 files...

  [1/2] code-quality
    └─ src/api/users.ts... 2 findings ($0.02, 8.1K tokens)
    └─ src/api/auth.ts... 1 finding ($0.01, 4.3K tokens)
    └─ src/utils/jwt.ts... 1 finding ($0.01, 3.8K tokens)

  [2/2] security-audit
    └─ src/api/auth.ts... 1 finding ($0.01, 5.2K tokens)

✓ code-quality: 3 findings
✓ security-audit: 1 finding

💰 Cost: $0.05 (21.4K tokens, 8.7K cached)

​
Environment Variables

​
ANTHROPIC_API_KEY

API key for authentication: 
export ANTHROPIC_API_KEY=sk-ant-...
warden

​
WARDEN_ANTHROPIC_API_KEY

Warden-specific API key (takes precedence): 
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...
warden

​
GITHUB_TOKEN

GitHub token for API access: 
export GITHUB_TOKEN=ghp_...
warden

​
NO_COLOR

Disable colored output: 
export NO_COLOR=1
warden

​
Tips

Use git diff syntax:
warden main..HEAD
Use --skill flag:
warden --skill security-audit
Use --output flag:
warden --output logs/$(date +%Y%m%d).jsonl
Use --fail-on flag:
# Fail on high or above
warden --fail-on high

# Never fail (report only)
warden --fail-on off

Auto-fix

Apply suggested fixes automatically

Configuration

Configure skill behavior

Output formats

JSON, JSONL, and GitHub outputs

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us