# vibecheck-ai — CLI

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

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`.

```bash
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.

```bash
vibecheck docguard
```

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

**Artifacts:** `.vibecheck/docguard/`

---

### `help`

```bash
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.

```bash
# 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](../../README.md#pricing) for details.

---

## License

MIT