> ## Documentation Index
> Fetch the complete documentation index at: https:// zenveil.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Complete command reference for the ZenVeil CLI. Every command, every flag, every option.

## Command structure

```
zenveil [--verbose] <command> [arguments] [flags]
```

## Global flags

| Flag        | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `--verbose` | Enable debug logging — shows scanner internals, HTTP requests, and AI token streaming |

## Command groups

<CardGroup cols={2}>
  <Card title="Scanning" icon="magnifying-glass">
    `scan github` · `scan api`

    Point ZenVeil at a target and get findings with animated multi-step progress.
  </Card>

  <Card title="Findings" icon="list">
    `list` · `stats` · `ignore`

    Browse, filter, and suppress findings from the last scan.
  </Card>

  <Card title="AI Analysis" icon="wand-magic-sparkles">
    `explain` · `fix` · `triage` · `agent`

    Claude-powered explanations, fixes, and prioritization. `explain` and `fix` require **Pro**.
  </Card>

  <Card title="Account" icon="user">
    `login` · `whoami` · `upgrade` · `billing`

    Manage your API key, view your plan, and handle subscriptions.
  </Card>

  <Card title="Reporting" icon="file-export">
    `report json` · `report html`

    Export the last scan to structured JSON or a shareable HTML report.
  </Card>

  <Card title="Docs" icon="book">
    `docs` · `docs auth` · `docs secrets` · `docs supply-chain` · `docs api`

    Open documentation in your browser from the terminal.
  </Card>
</CardGroup>

## Full command reference

### Account

| Command                        | Description                                                        |
| ------------------------------ | ------------------------------------------------------------------ |
| `zenveil login`                | Show step-by-step guide then prompt securely for your API key      |
| `zenveil login <api-key>`      | Save key directly (for scripts — prefer `ZENVEIL_API_KEY` env var) |
| `zenveil whoami`               | Show your email and current plan                                   |
| `zenveil upgrade`              | Upgrade to Pro or Team (opens Stripe checkout in browser)          |
| `zenveil upgrade pro --annual` | Upgrade with annual billing                                        |
| `zenveil billing`              | Manage subscription — cancel, change plan, update card             |

### Scanning

| Command                                            | Description                                |
| -------------------------------------------------- | ------------------------------------------ |
| `zenveil scan github <owner/repo>`                 | Scan a GitHub repository                   |
| `zenveil scan github <owner/repo> --token <tok>`   | Use a GitHub token (or set `GITHUB_TOKEN`) |
| `zenveil scan github <owner/repo> --ref <branch>`  | Scan a specific branch, tag, or commit     |
| `zenveil scan github <owner/repo> --check-cves`    | Include CVE checks via OSV.dev             |
| `zenveil scan github <owner/repo> --exclude-tests` | Skip test/fixture/example files entirely   |
| `zenveil scan api <url>`                           | Scan an API endpoint for security headers  |

### Findings

| Command                                 | Description                                                             |
| --------------------------------------- | ----------------------------------------------------------------------- |
| `zenveil list`                          | List all findings from the last scan                                    |
| `zenveil list --severity high,critical` | Filter by severity level(s)                                             |
| `zenveil list --scanner secrets`        | Filter by scanner name                                                  |
| `zenveil stats`                         | Show scan statistics (target, duration, counts by severity and scanner) |
| `zenveil ignore <id>`                   | Suppress a finding from future reports                                  |
| `zenveil ignore <id> --reason "text"`   | Suppress with a documented reason                                       |

### AI analysis

<Info>
  `explain` and `fix` require a **Pro** plan. `triage` is available on all plans.
  Run `zenveil upgrade` to unlock per-finding AI features.
</Info>

| Command                                               | Plan | Description                                      |
| ----------------------------------------------------- | ---- | ------------------------------------------------ |
| `zenveil explain <id>`                                | Pro  | AI explanation of a finding                      |
| `zenveil fix <id>`                                    | Pro  | AI-generated fix with syntax-highlighted output  |
| `zenveil fix <id> --auto-pr --repo <r>`               | Pro  | Generate a fix and open a GitHub PR              |
| `zenveil fix <id> --auto-pr --repo <r> --token <tok>` | Pro  | Use a specific GitHub token                      |
| `zenveil triage`                                      | Free | AI-prioritized remediation plan for all findings |

### Reporting

| Command                      | Description              |
| ---------------------------- | ------------------------ |
| `zenveil report json <file>` | Export last scan to JSON |
| `zenveil report html <file>` | Export last scan to HTML |

### Docs

| Command                     | Description                        |
| --------------------------- | ---------------------------------- |
| `zenveil docs`              | Open documentation home in browser |
| `zenveil docs auth`         | Authentication guide               |
| `zenveil docs secrets`      | Secrets scanner guide              |
| `zenveil docs supply-chain` | Supply-chain scanner guide         |
| `zenveil docs api`          | API scanner guide                  |

## Environment variables

| Variable          | Used by                        | Description                         |
| ----------------- | ------------------------------ | ----------------------------------- |
| `ZENVEIL_API_KEY` | All                            | Your ZenVeil API key                |
| `GITHUB_TOKEN`    | `scan github`, `fix --auto-pr` | GitHub personal access token        |
| `ZENVEIL_API_URL` | All (self-hosted)              | Override the scanning API URL       |
| `ZENVEIL_WEB_URL` | Billing (self-hosted)          | Override the billing/web server URL |

## Exit codes

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success — scan completed, no CRITICAL or HIGH findings          |
| `1`  | Security gate triggered — one or more CRITICAL or HIGH findings |
| `2`  | Error — invalid arguments, missing scan cache, network failure  |

Use exit codes in CI to gate deployments:

```bash theme={null}
zenveil scan repo . && echo "✓ Security gate passed" || echo "✗ Security issues found"
```

## Getting help

```bash theme={null}
zenveil help          # Formatted command listing with examples
zenveil --help        # argparse help
zenveil scan --help   # Subcommand help
```