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

# Installation

> Install ZenVeil on any platform in under two minutes. Python 3.8+, pip, done.

## Requirements

| Requirement | Minimum version | Notes |
| - | - | - |
| Python | 3.8+ | 3.11+ recommended |
| pip | 21.0+ | Ships with Python |
| OS | Linux, macOS, Windows | WSL2 supported on Windows |

## Install via pip

```bash theme={null}
pip install zenveil
```

Verify the installation:

```bash theme={null}
zenveil --version
# zenveil 1.0.0
```

## Install in a virtual environment (recommended)

Keep your global Python environment clean by using a virtual environment:

```bash macOS / Linux theme={null}
python -m venv .venv
source .venv/bin/activate
pip install zenveil
```

```bash Windows (PowerShell) theme={null}
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install zenveil
```

```bash Windows (CMD) theme={null}
python -m venv .venv
.venv\Scripts\activate.bat
pip install zenveil
```

## Install from source

For the latest unreleased changes:

```bash theme={null}
git clone https://github.com/zenveil/zenveil.git
cd zenveil
pip install -e .
```

## Configuration

### API key setup

Your API key is generated the first time you sign in at [zenveil.dev](https://zenveil.dev) and emailed to you immediately. It starts with `zv_live_` and is shown **once** — store it somewhere safe before closing the email.

Set it as an environment variable:

```bash theme={null}
export ZENVEIL_API_KEY="zv_live_your_key_here"
```

To make it permanent, add it to your shell profile:

```bash theme={null}
echo 'export ZENVEIL_API_KEY="zv_live_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

Or use `zenveil login` to authenticate interactively — this stores your key in `~/.zenveil/credentials` so you never have to export it manually.

> [!WARNING]
>
> **Lost your key?** Go to **Dashboard → Settings → API Key → Rotate Key**.
> A new key is generated immediately and emailed to you. Your old key stops working the moment you rotate.
> Update any CI/CD pipelines or `.env` files that reference the old key.

### Optional: AI analysis keys

AI-powered commands (`explain`, `fix`, `triage`, `agent`) use Claude. Set your Anthropic API key:

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-your_key_here"
```

Get your key at [console.anthropic.com](https://console.anthropic.com).

### Optional: GitHub token

GitHub scanning and auto-PR require a GitHub token with `repo` scope:

```bash theme={null}
export GITHUB_TOKEN="ghp_your_token_here"
```

Create a token at [github.com/settings/tokens](https://github.com/settings/tokens). Required scopes:

* `repo` — for private repository scanning and opening pull requests
* `public_repo` — for public repository scanning only

### Full environment setup

```bash theme={null}
# ~/.zshrc or ~/.bashrc

# Required for all ZenVeil operations
export ZENVEIL_API_KEY="zvk_live_your_key_here"

# Required for AI-powered commands (explain, fix, triage, agent)
export ANTHROPIC_API_KEY="sk-ant-your_key_here"

# Required for GitHub scanning and auto-PR
export GITHUB_TOKEN="ghp_your_token_here"
```

## Platform-specific notes

> [accordion] macOS
>
> ZenVeil works with the system Python 3 or any Homebrew/pyenv Python.
>
> ```bash theme={null}
> # Homebrew Python (recommended)
> brew install python@3.11
> pip3 install zenveil
>
> # pyenv
> pyenv install 3.11.0
> pyenv global 3.11.0
> pip install zenveil
> ```
>
> If you see a `command not found: zenveil` error, ensure `~/.local/bin` is on your `$PATH`:
>
> ```bash theme={null}
> export PATH="$HOME/.local/bin:$PATH"
> ```

> [accordion] Linux (Ubuntu/Debian)
>
> ```bash theme={null}
> sudo apt update
> sudo apt install python3 python3-pip python3-venv -y
> pip3 install --user zenveil
> ```
>
> If installing globally in CI:
>
> ```bash theme={null}
> sudo pip3 install zenveil
> ```

> [accordion] Windows (WSL2)
>
> ZenVeil runs natively in WSL2 (Windows Subsystem for Linux). Follow the Linux instructions inside your WSL2 shell.
>
> Native Windows support via PowerShell is experimental. WSL2 is the recommended path.

> [accordion] Docker
>
> Run ZenVeil in a container without any local Python installation:
>
> ```dockerfile theme={null}
> FROM python:3.11-slim
> RUN pip install zenveil
> WORKDIR /scan
> ENTRYPOINT ["zenveil"]
> ```
>
> ```bash theme={null}
> docker build -t zenveil .
> docker run --rm -v $(pwd):/scan \
>   -e ZENVEIL_API_KEY=$ZENVEIL_API_KEY \
>   zenveil scan repo /scan
> ```

## Upgrading

```bash theme={null}
pip install --upgrade zenveil
```

Check the current version:

```bash theme={null}
zenveil --version
```

## Uninstalling

```bash theme={null}
pip uninstall zenveil
```

ZenVeil stores scan caches in `.zenveil-last-scan.json` (in your project directory) and credentials in `~/.zenveil/`. Remove them manually if needed:

```bash theme={null}
rm -f .zenveil-last-scan.json .zenveil-ignore.json
rm -rf ~/.zenveil
```

## Troubleshooting

> [accordion] `zenveil: command not found`
>
> The pip scripts directory is not on your `$PATH`.
>
> ```bash theme={null}
> # Find where pip installs scripts
> python -m site --user-base
> # Add /path/to/site-packages/../bin to $PATH
> export PATH="$(python -m site --user-base)/bin:$PATH"
> ```

> [accordion] `ModuleNotFoundError: No module named 'anthropic'`
>
> The `anthropic` package is not installed in the active environment.
>
> ```bash theme={null}
> pip install anthropic
> # or reinstall zenveil which pulls it as a dependency
> pip install --force-reinstall zenveil
> ```

> [accordion] SSL certificate errors on corporate networks
>
> If your company uses a custom CA bundle:
>
> ```bash theme={null}
> pip install --cert /path/to/company-ca.crt zenveil
> ```

> [accordion] Permission denied on pip install
>
> Never use `sudo pip`. Instead, install to user scope:
>
> ```bash theme={null}
> pip install --user zenveil
> ```
>
> Or use a virtual environment (recommended).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.