> ## 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.
# Quick Start
> From zero to your first security scan in 60 seconds.
## Your first scan
ZenVeil requires Python 3.8+. Install from PyPI:
```bash theme={null}
pip install zenveil
```
Verify the install:
```bash theme={null}
zenveil --help
```
Use a virtual environment to keep your global Python environment clean:
```bash theme={null}
python -m venv .venv && source .venv/bin/activate
pip install zenveil
```
```bash theme={null}
zenveil login
```
This displays a step-by-step guide, then prompts you to paste your API key — the input is hidden (like a `sudo` password). The key is saved to `~/.zenveil/credentials` and never appears in shell history or process listings.
```
╭──────────────────────────────────────────────────────────────────╮
│ │
│ 🔐 ZenVeil Authentication │
│ │
│ 1 Open https://zenveil.dev │
│ 2 Sign up — free, no credit card needed │
│ 3 Go to Settings → API Keys and copy your key │
│ 4 Paste below — key is hidden, never saved to shell history │
│ │
╰──────────────────────────────────────────────────────────────────╯
Paste your API key (hidden):
```
Check your email and plan any time with `zenveil whoami`.
Point ZenVeil at any directory:
```bash theme={null}
zenveil scan repo .
```
Or scan a remote GitHub repository directly — no clone required:
```bash theme={null}
zenveil scan github owner/repo
```
You'll see output like this:
```
╭──────────────────────────────────────────────────────────────────╮
│ ZenVeil Security Scan │
│ Target: /your/project · Scanners: secrets, supply_chain │
╰──────────────────────────────────────────────────────────────────╯
┌──────────┬──────────┬───────────────┬─────────────────────────────────────────┐
│ ID │ Severity │ Scanner │ Title │
├──────────┼──────────┼───────────────┼─────────────────────────────────────────┤
│ ZG-A1B2 │ CRITICAL │ secrets │ AWS access key │
│ ZG-C3D4 │ HIGH │ secrets │ .env file committed to repository │
│ ZG-E5F6 │ HIGH │ supply_chain │ Dependency confusion risk │
│ ZG-G7H8 │ MEDIUM │ secrets │ Token stored in browser storage │
└──────────┴──────────┴───────────────┴─────────────────────────────────────────┘
4 finding(s) · CRITICAL: 1 · HIGH: 2 · MEDIUM: 1
Run `zenveil explain ZG-A1B2` for AI analysis.
Run `zenveil fix ZG-A1B2` for an AI-generated fix.
```
ZenVeil uses Claude to explain what every finding means and why it matters:
```bash theme={null}
zenveil explain ZG-A1B2
```
```
Explaining ZG-A1B2: AWS access key
An AWS access key (AKIA...) was found committed in plain text at
src/config.js:14. AWS access keys grant programmatic access to your
AWS account. If this key is in a public or shared repository, anyone
can use it to access your S3 buckets, spin up EC2 instances, query
your databases, or run up significant AWS charges.
AWS automatically detects and notifies you of exposed keys, but the
window between exposure and detection can be hours. Attackers scan
GitHub continuously for newly committed AWS keys.
OWASP Category: A02:2021 — Cryptographic Failures
Confidence: 95%
Immediate actions:
1. Revoke this key in the AWS IAM console right now
2. Run `git rm --cached src/config.js` to untrack the file
3. Add `.env` to `.gitignore`
4. Use AWS Secrets Manager or environment variables for runtime access
```
Generate an AI fix and open a GitHub pull request automatically:
```bash theme={null}
zenveil fix ZG-A1B2 --auto-pr --repo owner/your-repo
```
```
Generating fix for ZG-A1B2: AWS access key
Applying redaction directly (no API key needed).
Opened pull request: https://github.com/owner/your-repo/pull/42
```
ZenVeil creates a PR that redacts the secret and adds `.env` to `.gitignore`. Review and merge.
## What's next?
Scan any public repository — or private ones with a token — without cloning.
Gate your pull requests on security findings. ZenVeil exits with code 1 on CRITICAL/HIGH.
Get a prioritized remediation plan for all findings, ranked by risk and effort.
Embed ZenVeil scanning directly into your platform via REST API.
## Environment variables cheatsheet
| Variable | Required for | Example |
| ----------------- | ------------------------------------------------- | ------------------------------------- |
| `ZENVEIL_API_KEY` | All CLI commands (alternative to `zenveil login`) | `zvk_live_...` |
| `GITHUB_TOKEN` | GitHub scanning, `fix --auto-pr` | `ghp_...` |
| `ZENVEIL_API_URL` | Self-hosted scanning API | `https://api.zenveil.dev` |
| `ZENVEIL_WEB_URL` | Self-hosted billing server | `https://zenveil-server.onrender.com` |
Set them in your shell profile or CI secrets:
```bash theme={null}
export ZENVEIL_API_KEY="zvk_live_your_key_here"
export GITHUB_TOKEN="ghp_your_github_token"
```