vibecheck-ai — CLI

Find bad AI-generated code. Fix it. Prevent it.

npm install -g vibecheck-ai

Commands

VibeCheck CLI has 12 commands. Every command writes artifacts to .vibecheck/ and supports --format text|json|sarif, --output <path>, --quiet, --verbose, and --no-color.

kickoff

Initialize the .vibecheck/ workspace. Generates config.json, truthpack.json, and codegraph.json.

vibecheck kickoff --yes          # Non-interactive, accept defaults
vibecheck kickoff --connect      # Also set up GitHub CI workflow

Artifacts: config.json, truthpack.json, codegraph.json

scan

Run 17+ scanning engines across your codebase.

vibecheck scan                                   # Default scan (all engines)
vibecheck scan full                              # Explicit full scan
vibecheck scan --secrets --format json           # Secrets only, JSON output
vibecheck scan --ghost --format text             # Ghost imports/routes only
vibecheck scan --security --severity high        # Security, high+ only
vibecheck scan --mock --output findings.json     # Mock data, write to file
vibecheck scan --changed                         # Only git-changed files
vibecheck scan --baseline prev-findings.json     # Show only new findings

Category flags:

| Flag | Engines activated | |------|-------------------| | --secrets | credentials, placeholder-scanner | | --mock | mock-detector, fake-features, fake-success-ui | | --endpoints | API endpoint validation | | --todo | placeholder-scanner, code-quality | | --ghost | hallucinations, import-reality, phantom-deps | | --security | security (OWASP Top 10) | | --quality | code-quality |

Filtering flags:

| Flag | Description | |------|-------------| | --severity <level> | Minimum severity: critical, high, medium, low | | --confidence <n> | Minimum confidence score 0–100 | | --changed | Scan only git-changed files | | --include <glob> | Include glob (repeatable) | | --exclude <glob> | Exclude glob (repeatable) | | --max <n> | Maximum findings to return | | --baseline <path> | Diff against previous findings.json |

Output: --format text|json|sarif

Artifacts: .vibecheck/runs/<runId>/findings.json, logs.txt

prove

Flagship validation gate. Orchestrates scan → reality (optional) → docguard → proof.

vibecheck prove                              # Standard profile
vibecheck prove --profile fast --strict      # Fast, fail on any warning
vibecheck prove --profile paranoid           # All engines, low thresholds, chaos
vibecheck prove --url http://localhost:3000  # Include reality smoke test

Profiles:

| Profile | Engines | Reality | Docguard | Changed-only | |---------|---------|---------|----------|-------------| | fast | secrets, ghost, endpoints, todo, quality | off | minimal | yes | | standard | + mock, security, fake-features | smoke (if URL) | + dupes | no | | paranoid | all engines, low confidence | smoke + chaos-lite | + coverage | no |

Flags:

| Flag | Description | |------|-------------| | --profile <name> | fast, standard, paranoid (default: standard) | | --strict | Exit 3 on any warning (not just blockers) | | --url <url> | Base URL for reality smoke test | | --skip-reality | Skip runtime verification stage | | --skip-docguard | Skip documentation checks |

Exit codes:

| Code | Meaning | |------|---------| | 0 | Pass | | 1 | Warnings (non-strict mode) | | 2 | Fail (policy violation) | | 3 | Runtime fail (reality) or strict-mode warnings | | 4 | Internal error |

Artifacts: .vibecheck/runs/<runId>/proof.json, findings.json, logs.txt

doctor

Diagnose project environment, dependencies, and configuration.

vibecheck doctor

Checks: Node.js version, package manager, TypeScript config, dependencies, .env files, git state, VibeCheck config, disk space.

Artifacts: .vibecheck/runs/<runId>/doctor.json

missionpack

Convert scan findings into task packs with prompts for AI agents.

vibecheck missionpack --from latest           # From latest scan
vibecheck missionpack --from-scan             # Alias
vibecheck missionpack --from-polish           # From polish output
vibecheck missionpack --goal auth             # Goal template
vibecheck missionpack start <taskId>          # Start a task
vibecheck missionpack complete <taskId>       # Mark complete
vibecheck missionpack progress                # Show progress
vibecheck missionpack --format github         # Export as GitHub Issues

Goal templates: auth, api, ui, test, database, deploy, performance

Artifacts: .vibecheck/missionpacks/

reality

Runtime verification — actually runs your app and tests if things work.

vibecheck reality --mode smoke --url http://localhost:3000
vibecheck reality --mode chaos --url http://localhost:3000 --seed 42
vibecheck reality --mode stress --url http://localhost:3000
vibecheck reality list                        # Show all modes and flows

Modes:

| Mode | Description | |------|-------------| | smoke | Homepage, console errors, links, images, API health | | chaos | Random clicks, invalid inputs, XSS/SQLi, resize, storage clear | | stress | Concurrent requests, rapid sequential, large payloads, p50/p95/p99 |

Requires Playwright (optional dependency). Falls back to HTTP checks if not installed.

forge

Generate guardrails, rules, skills, and agent definitions for your IDE.

vibecheck forge --rules                       # Generate rules only
vibecheck forge --guardrails                  # Generate guardrails
vibecheck forge --skills                      # Generate skills
vibecheck forge --agents                      # Generate agent definitions
vibecheck forge component UserProfile         # Generate a component

Writes to .cursor/rules/, .cursor/agents/, .cursor/skills/, .cursor/hooks/.

Artifacts: .vibecheck/forge/

polish

Deterministic code quality improvements.

vibecheck polish                                      # Default checks
vibecheck polish --categories types,readability       # Filter by category
vibecheck polish --aggressive                         # Include opinionated checks
vibecheck polish --apply                              # Auto-fix (where safe)

Categories: types, readability, performance, naming, structure, security, quality

Each suggestion includes severity (info/warning/error) and autoFixable flag.

firewall

Truthpack-based drift detection and intent locking.

vibecheck firewall --mode shield              # Enable shield mode
vibecheck firewall drift                      # Check for truthpack drift
vibecheck firewall intent "Add auth"          # Lock intent
vibecheck firewall clear-intent               # Clear intent lock
vibecheck firewall hook                       # Install git pre-commit hook
vibecheck firewall unhook                     # Remove hook
vibecheck firewall status                     # Show current state

Modes: off, observe, enforce (shield), lockdown

Artifacts: .vibecheck/firewall/firewall-log.json

autofix

Generate fix plans from scan findings. Dry-run by default — no code is modified unless you pass --apply.

vibecheck autofix --from latest --dry-run     # Preview fixes (default)
vibecheck autofix --from latest --apply       # Apply fixes
vibecheck autofix --run <runId>               # From specific run
vibecheck autofix --patch fixes.patch         # Write unified diff
vibecheck autofix --kinds secrets,todo        # Fix only these categories
vibecheck autofix --no-deletions              # Never delete code

Fix categories: secrets, todo, mock, ghost

Safety rules:

• Dry-run is the default. Pass --apply explicitly to modify files.
• Never edits files outside include/exclude scope.
• Never deletes code unless dead/unreferenced, confidence ≥ 90, and deletions enabled.
• Requires git clean state or backs up modified files.

Artifacts: .vibecheck/runs/<runId>/fixplan.json

docguard

Documentation quality and coverage analysis.

vibecheck docguard

Checks for duplicate docs, stale docs, test coverage gaps, and cache cleanup.

Artifacts: .vibecheck/docguard/

help

vibecheck help              # Show all commands
vibecheck help scan         # Show help for a specific command

Global Flags

These flags work with every command:

| Flag | Description | |------|-------------| | --format text\|json\|sarif | Output format | | --output <path> | Write output to file | | -q, --quiet | Minimal stdout | | -v, --verbose | Extra context + debug | | --no-color | CI-friendly (no ANSI) | | --truthpack | Regenerate truthpack before running | | --codegraph | Regenerate codegraph before running |

Artifacts Layout

.vibecheck/
  config.json
  truthpack.json
  codegraph.json
  runs/<runId>/
    findings.json
    fixplan.json
    proof.json
    logs.txt
  cache/
  missionpacks/
  forge/
  firewall/
  docguard/

Backward Compatibility

Breaking Change: ship → prove

The ship command has been removed in v6.0.0. Use prove instead.

# Before (v5.x)
vibecheck ship
vibecheck ship --strict

# After (v6.0.0+)
vibecheck prove
vibecheck prove --profile standard --strict

There is no alias. The ship command will produce an error in v6.0.0+.

Pricing

The CLI is free for all users, with no feature restrictions.

The MCP Server and VS Code Extension require a subscription ($9.99/month). See the root README for details.

License

MIT