CLI Reference
Commands
bouncerfox scan [paths...]
Main scanning command. Scans files or directories for AI agent configuration issues. Defaults to current directory.
bouncerfox scan .
bouncerfox scan CLAUDE.md .mcp.json
bouncerfox scan . --format json --severity high --verbose
Flags:
| Flag | Default | Description |
|---|---|---|
--format, -f | table | Output format: table, json, sarif |
--severity, -s | (from config) | Severity floor: critical, high, warn, info |
--config, -c | (auto-discovered) | Path to config file (overrides auto-discovery) |
--max-findings | 0 (unlimited) | Cap total findings |
--github-comment | false | Post PR comment and check run (requires GITHUB_TOKEN) |
--pr-number | (auto-detected) | PR number for GitHub integration |
--target | (auto-detected) | Override scan target identity |
--trigger | (auto-detected) | Override trigger detection: ci or local |
--offline-behavior | (auto) | Behavior when platform is unreachable: warn or fail-closed. Auto: fail-closed in CI, warn locally. |
--dry-run-upload | false | Preview upload payload without sending |
--strip-paths | false | Send filenames only (no full paths) in upload |
--anonymous | false | Strip all identifying info from upload |
--no-cache | false | Skip config cache (always pull fresh from platform) |
--group-by | file | Group findings by: file, rule, severity |
--verbose, -v | false | Show code frames with context lines |
--no-color | false | Disable colors and Unicode symbols |
bouncerfox rules
List all registered rules with their ID, severity, category, and description.
bouncerfox rules
bouncerfox init
Generate a default .bouncerfox.yml in the current directory. Fails if the file already exists.
bouncerfox init
bouncerfox auth
Authenticate with the BouncerFox platform. Opens a browser to the platform dashboard, then prompts you to paste your API key. Saves the key to ~/.config/bouncerfox/credentials.
The platform is currently in development. For now, set BOUNCERFOX_API_KEY as an environment variable instead.
bouncerfox auth
bouncerfox config refresh
Clear the cached platform config. Useful when org-level rules have changed and you want to pull fresh config on the next scan.
bouncerfox config refresh
bouncerfox completion [shell]
Generate shell completion scripts for bash, zsh, fish, or powershell.
bouncerfox completion bash > /etc/bash_completion.d/bouncerfox
bouncerfox completion zsh > "${fpath[1]}/_bouncerfox"
bouncerfox version
Print the installed version.
bouncerfox version
Exit Codes
| Code | Meaning |
|---|---|
0 | No findings at or above severity threshold (or pass/informational verdict from platform) |
1 | One or more findings found (or fail verdict from platform) |
2 | Scanner error (or platform unreachable in fail-closed mode) |
Environment Variables
| Variable | Description |
|---|---|
BOUNCERFOX_API_KEY | Platform API key. Enables connected mode (config pull, upload, verdict). |
BOUNCERFOX_PLATFORM_URL | Platform API base URL (default: https://api.bouncerfox.dev) |
BOUNCERFOX_CONFIG_DIR | Config directory override (default: ~/.config/bouncerfox) |
BOUNCERFOX_TARGET | Override scan target identity |
GITHUB_TOKEN | Required for --github-comment |
NO_COLOR | Disable colors and Unicode (any value) |
GITHUB_ACTIONS | Auto-detected in GitHub Actions |
CI | Auto-detected in CI environments |
GITHUB_SHA | Commit SHA (auto-detected) |
GITHUB_REF_NAME | Branch name (auto-detected) |
GITHUB_REPOSITORY | Repository (auto-detected) |
GITHUB_EVENT_PATH | Event payload path (auto-detected) |
Limits
| Limit | Value |
|---|---|
| Max file size | 1 MB |
| Max scannable files | 500 |
| Max JSON nesting depth | 10 levels |
| Scan timeout | 5 minutes |