guardrail CLI v2.5.0 🎉

The official command-line interface for guardrail - AI-native code security and guardrail platform.

CLI entry (canonical)

Integration tests for the CLI are not run by Jest (see root config/jest.config.js). From packages/cli run:

pnpm run build
pnpm exec playwright install chromium   # once per machine/CI
pnpm run test:integration
# or: pnpm exec playwright test tests/integration/cli-features.test.ts

Reality integration (heavy Playwright): opt-in with GUARDRAIL_REALITY_INTEGRATION=1 if you remove reality-integration.test.ts from Jest ignore patterns.

✨ What's New in v2.5.0

• 🎮 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

Installation

npm install -g guardrail-cli-tool@latest

Quick Start

# 🎮 Open the new interactive menu (recommended)
guardrail menu

# 🔐 Authenticate with your API key
guardrail auth --key gr_pro_your_api_key_here

# 🔍 Scan your project
guardrail scan --path ./your-project

# 🚀 Try Reality Mode (auto-installs Playwright)
guardrail reality --url https://your-site.com --flow user-journey

# 📦 Ship readiness check
guardrail ship --path ./your-project

Authentication

The CLI uses enterprise-grade authentication with secure credential storage.

Commands

# Authenticate with API key (validates against guardrail API)
guardrail auth --key gr_pro_abc123xyz789

# Check current authentication status
# Shows masked key (gr_pro_****xyz9), tier, email, expiry
guardrail auth --status

# Force refresh cached entitlements
guardrail auth --refresh

# Logout and remove stored credentials
guardrail auth --logout

Features

• Real API Validation: Keys are validated against POST /v1/cli/auth/validate
• 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 --refresh to force
• Key Masking: API keys always displayed masked: gr_pro_****abcd
• Expiry Warnings: Yellow warning if entitlements expire within 72 hours

Credential Storage

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 menu

Init Command

The guardrail init command provides enterprise-grade project initialization with automatic framework detection and template-based configuration.

Basic Usage

# Initialize with interactive prompts (auto-detects framework)
guardrail init

# Initialize with a specific template
guardrail init --template enterprise

# Initialize with CI and git hooks
guardrail init --ci --hooks

# Non-interactive mode
guardrail init --template startup --no-interactive

Options

Framework Detection

guardrail automatically detects your project framework by inspecting package.json and file structure:

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

Templates

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

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

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

guardrail init --template oss

Generated Files

Configuration (.guardrail/config.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 (.github/workflows/guardrail.yml)

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

Examples

# Next.js project with enterprise security
guardrail init --template enterprise --ci --hooks

# Express API with startup defaults
guardrail init --path ./api --template startup

# OSS project with lefthook
guardrail init --template oss --hooks --hook-runner lefthook

# CI-only setup (no hooks)
guardrail init --template enterprise --ci --no-interactive

Vulnerability Scanning (OSV Integration)

The scan:vulnerabilities command uses real-time data from the Open Source Vulnerabilities (OSV) database.

Features

• 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

Usage

# Basic vulnerability scan
guardrail scan:vulnerabilities --path ./my-project

# Bypass cache for fresh data
guardrail scan:vulnerabilities --no-cache

# Enable NVD enrichment for CVSS scores (slower)
guardrail scan:vulnerabilities --nvd

# Output as SARIF for GitHub code scanning
guardrail scan:vulnerabilities --format sarif -o results.sarif

# Filter by ecosystem
guardrail scan:vulnerabilities --ecosystem npm

# Fail CI if critical vulnerabilities found
guardrail scan:vulnerabilities --fail-on-critical

Options

Cache Management

Vulnerability data is cached for 24 hours in .guardrail/cache/osv.json.

# View cache statistics
guardrail cache:status

# Clear the cache
guardrail cache:clear

# Clear global cache
guardrail cache:clear --global

SARIF Output for GitHub

Generate SARIF v2.1.0 output for GitHub code scanning:

# Generate SARIF report
guardrail scan:vulnerabilities --format sarif -o vuln-results.sarif

# In 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

Consistent Command Headers

All analysis commands (scan, 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

Reality Mode

Reality Mode detects fake data, mock backends, and placeholder content in your running application using Playwright browser automation.

Generate Only (default)

# Generate a Playwright test for the auth flow
guardrail reality --flow auth

# Generate test for a custom URL
guardrail reality --url http://localhost:8080 --flow checkout

Generate + Run

# Generate and immediately execute the test
guardrail reality --run --flow auth

# Run in headed mode (show browser)
guardrail reality --run --flow auth --headless=false

# Custom timeout and workers
guardrail reality --run --timeout 60 --workers 2

# Use HTML reporter for detailed results
guardrail reality --run --reporter html,list

# Full 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 codegen to capture user actions.

# Start recording session
guardrail reality --record --url http://localhost:3000

# Record 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 .guardrail/reality/<runId>/reality-<flow>.test.ts
5. Press Ctrl+C when done

Options

Artifacts

When using --run, artifacts are saved under .guardrail/reality/<runId>/:

.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

Viewing Results

HTML Report (if --reporter html):

npx playwright show-report .guardrail/reality/<runId>/report

JSON Results:

cat .guardrail/reality/<runId>/result.json

Logs:

cat .guardrail/reality/<runId>/output.log

Prerequisites

Reality Mode requires Playwright and browser binaries.

Install Playwright:

npm install -D @playwright/test
npx playwright install

The CLI automatically detects missing dependencies and provides exact install commands with exit code 2.

Exit Codes

Examples

Quick test in CI:

guardrail reality --run --flow auth --headless --timeout 30

Debug with full visibility:

guardrail reality --run --flow checkout \
  --no-headless \
  --trace on \
  --video on \
  --screenshot on

Record custom flow:

guardrail reality --record --url http://localhost:3000 --flow onboarding

Parallel execution:

guardrail reality --run --workers 4 --reporter html,json

Support

• Documentation
• Discord
• Support

License

MIT