Guardrail CLI - Enterprise security scanning with interactive menu, arrow navigation, and auto-installation
npm install guardrail-cliThe official command-line interface for Guardrail - AI-native code security and guardrail platform.
- 🎮 Interactive Menu - Arrow key navigation, visual selection indicators
- 🎭 Reality Mode - Automatic Playwright installation for browser testing
- 📦 Ship Check - Plain English audit and deployment readiness
- 🛠️ AI Fixes - Enhanced guided suggestions and automated remediation
- 🧪 Full Test Coverage - 50+ integration tests ensuring reliability
``bash`
npm install -g guardrail-cli@latest
`bash🎮 Open the new interactive menu (recommended)
guardrail menu
Authentication
The CLI uses enterprise-grade authentication with secure credential storage.
$3
bash
Authenticate with API key (validates against Guardrail API)
guardrail auth --key gr_pro_abc123xyz789Check current authentication status
Shows masked key (gr_pro_**xyz9), tier, email, expiry
guardrail auth --statusForce refresh cached entitlements
guardrail auth --refreshLogout and remove stored credentials
guardrail auth --logout
`$3
- Real API Validation: Keys are validated against
- Secure Storage: Credentials stored with 0600 permissions (Unix) or NTFS ACLs (Windows)
- Local Caching: Entitlements cached for 15 minutes to reduce API calls
- Auto-Refresh: Cache reused if > 5 minutes remaining; use to force
- Key Masking: API keys always displayed masked: gr_pro_**abcd
- Expiry Warnings: Yellow warning if entitlements expire within 72 hours$3
| Platform | Location |
| -------- | ---------------------------------------------------- |
| macOS |
|
| Linux | ~/.config/guardrail/state.json |
| Windows | %APPDATA%\guardrail\state.json |If
keytar is available, sensitive tokens are stored in the OS keychain.Commands
-
guardrail auth - Authenticate with your API key
- guardrail scan - Run security scans
- guardrail scan:secrets - Scan for hardcoded secrets
- guardrail scan:vulnerabilities - Scan dependencies for CVEs (OSV integration)
- guardrail scan:compliance - Compliance assessment (Pro)
- guardrail sbom:generate - Generate SBOM (Pro)
- guardrail ship - Ship readiness checks (Starter+)
- guardrail reality - Browser testing for fake data (Starter+)
- guardrail smells - Code smell analysis
- guardrail fix - Manual fix suggestions (Starter+)
- guardrail autopilot - AI-powered batch remediation (Pro)
- guardrail cache:clear - Clear OSV vulnerability cache
- guardrail cache:status - Show cache statistics
- guardrail init - Initialize Guardrail in a project (see Init Command)
- guardrail menu - Interactive menuInit Command
The
guardrail init command provides enterprise-grade project initialization with automatic framework detection and template-based configuration.$3
`bash
Initialize with interactive prompts (auto-detects framework)
guardrail initInitialize with a specific template
guardrail init --template enterpriseInitialize with CI and git hooks
guardrail init --ci --hooksNon-interactive mode
guardrail init --template startup --no-interactive
`$3
| Option | Description |
| --------------------------- | ---------------------------------------------------------- |
|
| Project path (default: .) |
| -t, --template | Template: startup, enterprise, or oss |
| --ci | Generate CI/CD workflow (GitHub Actions with SARIF upload) |
| --hooks | Install git hooks (husky or lefthook) |
| --hook-runner | Specify hook runner: husky or lefthook |
| --no-interactive | Disable interactive prompts |$3
Guardrail automatically detects your project framework by inspecting
package.json and file structure:| Framework | Detection Signals |
| -------------- | ------------------------------------------------------------------ |
| Next.js |
next dependency, next.config.*, app/ or pages/ directory |
| Express | express dependency, src/server.* patterns, routes/ directory |
| NestJS | @nestjs/core dependency, nest-cli.json, *.module.ts files |
| Fastify | fastify dependency, @fastify/* packages |
| Remix | @remix-run/ packages, remix.config., app/routes/ |
| Vite+React | vite + react dependencies, @vitejs/plugin-react |Based on the detected framework, Guardrail recommends the most relevant scans:
- Next.js/Remix: secrets, vulnerabilities, ship readiness, reality mode (auth flows)
- Express/NestJS/Fastify: secrets, vulnerabilities, ship readiness, compliance (logging/rate limits)
- Vite+React: secrets, vulnerabilities, ship readiness
$3
Templates configure
.guardrail/config.json with different defaults:#### Startup Template
- Use case: Early-stage teams, fast iteration
- Scan thresholds: High (fewer alerts)
- Compliance: Disabled
- Gating: Block on critical only
- Output: Table format
- Noise reduction: Suppress test files, low-confidence findings
`bash
guardrail init --template startup
`#### Enterprise Template
- Use case: Regulated industries, strict security requirements
- Scan thresholds: Low (catch everything)
- Compliance: Enabled (SOC2 by default)
- Gating: Block on critical and high, baseline/allowlist enabled
- Output: SARIF format with upload
- SBOM: Enabled
bash
guardrail init --template enterprise
`#### OSS Template
- Use case: Open source projects, contributor-friendly
- Focus: Supply chain security (SBOM, vulnerabilities)
- Gating: Permissive, baseline/allowlist enabled
- Output: Markdown format (PR-friendly)
- Noise reduction: Suppress test files, examples
bash
guardrail init --template oss
`$3
#### Configuration (
)`json
{
"version": "1.0.0",
"template": "enterprise",
"framework": "nextjs",
"scans": {
"secrets": { "enabled": true, "threshold": "low" },
"vulnerabilities": { "enabled": true, "threshold": "medium" },
"compliance": { "enabled": true, "frameworks": ["soc2"] },
"sbom": { "enabled": true }
},
"gating": {
"enabled": true,
"blockOnCritical": true,
"blockOnHigh": true,
"baselineEnabled": true,
"allowlistEnabled": true
},
"output": {
"format": "sarif",
"sarifUpload": true,
"badgeGeneration": true
}
}
`#### CI Workflow (
)When using
--ci, generates a GitHub Actions workflow that:- Runs secrets and vulnerability scans
- Runs compliance checks (if enabled)
- Generates SBOM (if enabled)
- Uploads SARIF results to GitHub Security tab
- Runs ship readiness check
- Fails the workflow on critical/high findings
Required: Add
GUARDRAIL_API_KEY to your repository secrets.#### Git Hooks (
.husky/ or lefthook.yml)When using
--hooks, installs:- pre-commit: Secrets scan on staged files
- pre-push: Full secrets + vulnerability scan + ship check
$3
`bash
Next.js project with enterprise security
guardrail init --template enterprise --ci --hooksExpress API with startup defaults
guardrail init --path ./api --template startupOSS project with lefthook
guardrail init --template oss --hooks --hook-runner lefthookCI-only setup (no hooks)
guardrail init --template enterprise --ci --no-interactive
`Vulnerability Scanning (OSV Integration)
The
command uses real-time data from the Open Source Vulnerabilities (OSV) database.$3
- Real-time OSV API queries - Live vulnerability data from Google's OSV database
- Multi-ecosystem support - npm, PyPI, RubyGems, Go
- Lockfile parsing - package-lock.json, pnpm-lock.yaml, yarn.lock
- 24-hour caching - Reduces API calls with local cache in
.guardrail/cache/osv.json
- CVSS scoring - Severity levels with optional NVD enrichment
- Remediation paths - Upgrade suggestions with breaking change detection
- SARIF output - GitHub code scanning integration$3
bash
Basic vulnerability scan
guardrail scan:vulnerabilities --path ./my-projectBypass cache for fresh data
guardrail scan:vulnerabilities --no-cacheEnable NVD enrichment for CVSS scores (slower)
guardrail scan:vulnerabilities --nvdOutput as SARIF for GitHub code scanning
guardrail scan:vulnerabilities --format sarif -o results.sarifFilter by ecosystem
guardrail scan:vulnerabilities --ecosystem npmFail CI if critical vulnerabilities found
guardrail scan:vulnerabilities --fail-on-critical
`$3
| Option | Description |
| ----------------------- | ---------------------------------------------------------- |
|
| Project path to scan (default: .) |
| -f, --format | Output format: table, json, sarif (default: table) |
| -o, --output | Write report to file |
| --no-cache | Bypass 24h cache, fetch fresh data from OSV |
| --nvd | Enable NVD enrichment for CVSS scores (slower) |
| --fail-on-critical | Exit with error if critical vulnerabilities found |
| --fail-on-high | Exit with error if high+ vulnerabilities found |
| --ecosystem | Filter by ecosystem: npm, PyPI, RubyGems, Go |$3
Vulnerability data is cached for 24 hours in
.guardrail/cache/osv.json.`bash
View cache statistics
guardrail cache:statusClear the cache
guardrail cache:clearClear global cache
guardrail cache:clear --global
`$3
Generate SARIF v2.1.0 output for GitHub code scanning:
bash
Generate SARIF report
guardrail scan:vulnerabilities --format sarif -o vuln-results.sarifIn GitHub Actions workflow:
- name: Run Guardrail Vulnerability Scan
run: guardrail scan:vulnerabilities --format sarif -o results.sarif- name: Upload SARIF to GitHub
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: results.sarif
`The SARIF output includes:
- Rule metadata with CVE/GHSA IDs
- CVSS scores and vectors
- Remediation suggestions
- Package.json line locations
- Direct vs transitive classification
$3
All analysis commands (
, ship, smells, etc.) display a consistent framed header with:- Title: Command name with icon
- Project: Project name from directory
- Path: Project path (truncated for long paths)
- Started: Timestamp when command started
- Mode: Tier badge when authenticated (FREE/STARTER/PRO/ENTERPRISE)
- Metadata: Command-specific options (e.g., scan type, severity filter)
The header respects
NO_COLOR environment variable and --no-color flag for CI/accessibility.Tiers
- Free: Basic scanning and validation
- Starter ($29/mo): Ship checks, reality mode, fix suggestions
- Pro ($99/mo): Advanced analysis, autopilot, smells detection, compliance
- Enterprise ($499/mo): Custom policies, SSO, dedicated support
Environment Variables
| Variable | Description |
| -------------------------- | ------------------------------------------------------------ |
|
GUARDRAIL_API_BASE_URL | Override API endpoint (default: https://api.guardrail.dev) |
| GUARDRAIL_NO_INTERACTIVE | Disable interactive prompts (1 to disable) |
| GUARDRAIL_NO_UNICODE | Disable Unicode output (1 for ASCII-only) |Reality Mode
Reality Mode detects fake data, mock backends, and placeholder content in your running application using Playwright browser automation.
$3
`bash
Generate a Playwright test for the auth flow
guardrail reality --flow authGenerate test for a custom URL
guardrail reality --url http://localhost:8080 --flow checkout
`$3
bash
Generate and immediately execute the test
guardrail reality --run --flow authRun in headed mode (show browser)
guardrail reality --run --flow auth --headless=falseCustom timeout and workers
guardrail reality --run --timeout 60 --workers 2Use HTML reporter for detailed results
guardrail reality --run --reporter html,listFull configuration example
guardrail reality --run \
--url http://localhost:8080 \
--flow checkout \
--timeout 45 \
--workers 4 \
--reporter html,json \
--trace retain-on-failure \
--video retain-on-failure \
--screenshot only-on-failure
`Exit Code: Mirrors Playwright's exit code (0 = pass, non-zero = fail)
#### 3. Record Mode
Opens Playwright in interactive recording mode using
to capture user actions.`bash
Start recording session
guardrail reality --record --url http://localhost:3000Record with custom flow name
guardrail reality --record --url http://localhost:8080 --flow signup
`How it works:
1. Opens browser with Playwright Inspector
2. Interact with your app (click, type, navigate)
3. Playwright records all actions with robust selectors
4. Generated test saved to
5. Press Ctrl+C when done$3
| Flag | Description | Default |
| ------------------------- | ------------------------------------------------------ | ----------------------- |
|
| Project path | . |
| -u, --url | Base URL of running app | http://localhost:3000 |
| -f, --flow | Flow to test: auth, checkout, dashboard | auth |
| -t, --timeout | Test timeout in seconds | 30 |
| --headless | Run in headless mode | false |
| --run | Execute the generated test immediately | false |
| --record | Open Playwright codegen for recording | false |
| --workers | Number of parallel workers | 1 |
| --reporter | Test reporter: list, dot, html, json | list |
| --trace | Trace mode: on, off, retain-on-failure, on-first-retry | retain-on-failure |
| --video | Video mode: on, off, retain-on-failure, on-first-retry | retain-on-failure |
| --screenshot | Screenshot mode: on, off, only-on-failure | only-on-failure |$3
When using
--run, artifacts are saved under .guardrail/reality/:`
.guardrail/reality/auth-1704123456789-a1b2c3d4/
├── reality-auth.test.ts # Generated test file
├── output.log # Playwright console output
├── result.json # Run result summary (success, exitCode, duration)
├── run-metadata.json # Execution configuration
├── screenshots/ # Failure screenshots (if --screenshot enabled)
│ ├── test-failed-1.png
│ └── test-failed-2.png
└── report/ # HTML report (if --reporter html)
└── index.html
$3
HTML Report (if
):`bash
npx playwright show-report .guardrail/reality//report
`JSON Results:
bash
cat .guardrail/reality//result.json
`Logs:
bash
cat .guardrail/reality//output.log
`$3
Reality Mode requires Playwright and browser binaries.
Install Playwright:
bash
npm install -D @playwright/test
npx playwright install
`The CLI automatically detects missing dependencies and provides exact install commands with exit code 2.
$3
| Code | Meaning |
| ---- | ------------------------------------ |
| 0 | Tests passed |
| 1 | Tests failed |
| 2 | Playwright or browsers not installed |
$3
Quick test in CI:
bash
guardrail reality --run --flow auth --headless --timeout 30
`Debug with full visibility:
bash
guardrail reality --run --flow checkout \
--no-headless \
--trace on \
--video on \
--screenshot on
`Record custom flow:
bash
guardrail reality --record --url http://localhost:3000 --flow onboarding
`Parallel execution:
bash
guardrail reality --run --workers 4 --reporter html,json
``- Documentation
- Discord
- Support
MIT