Installation

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

pip install zenveil

Verify the installation:

zenveil --version
# zenveil 1.0.0

Install in a virtual environment (recommended)

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

python -m venv .venv
source .venv/bin/activate
pip install zenveil

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install zenveil

python -m venv .venv
.venv\Scripts\activate.bat
pip install zenveil

Install from source

For the latest unreleased changes:

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 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:

export ZENVEIL_API_KEY="zv_live_your_key_here"

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

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.

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:

export ANTHROPIC_API_KEY="sk-ant-your_key_here"

Get your key at console.anthropic.com.

Optional: GitHub token

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

export GITHUB_TOKEN="ghp_your_token_here"

Create a token at 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

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

macOS

ZenVeil works with the system Python 3 or any Homebrew/pyenv Python.

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

export PATH="$HOME/.local/bin:$PATH"

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip python3-venv -y
pip3 install --user zenveil

If installing globally in CI:

sudo pip3 install zenveil

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.

Docker

Run ZenVeil in a container without any local Python installation:

FROM python:3.11-slim
RUN pip install zenveil
WORKDIR /scan
ENTRYPOINT ["zenveil"]

docker build -t zenveil .
docker run --rm -v $(pwd):/scan \
  -e ZENVEIL_API_KEY=$ZENVEIL_API_KEY \
  zenveil scan repo /scan

Upgrading

pip install --upgrade zenveil

Check the current version:

zenveil --version

Uninstalling

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:

rm -f .zenveil-last-scan.json .zenveil-ignore.json
rm -rf ~/.zenveil

Troubleshooting

`zenveil: command not found`

The pip scripts directory is not on your $PATH.

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

`ModuleNotFoundError: No module named 'anthropic'`

The anthropic package is not installed in the active environment.

pip install anthropic
# or reinstall zenveil which pulls it as a dependency
pip install --force-reinstall zenveil

SSL certificate errors on corporate networks

If your company uses a custom CA bundle:

pip install --cert /path/to/company-ca.crt zenveil

Permission denied on pip install

Never use sudo pip. Instead, install to user scope:

pip install --user zenveil

Or use a virtual environment (recommended).

Getting Started

Scanners

Integrations

Examples

Plans & Pricing

Requirements

Install via pip

Install in a virtual environment (recommended)

Install from source

Configuration

API key setup

Optional: AI analysis keys

Optional: GitHub token

Full environment setup

Platform-specific notes

Upgrading

Uninstalling

Troubleshooting

​Requirements

​Install via pip

​Install in a virtual environment (recommended)

​Install from source

​Configuration

​API key setup

​Optional: AI analysis keys

​Optional: GitHub token

​Full environment setup

​Platform-specific notes

​Upgrading

​Uninstalling

​Troubleshooting

Requirements

Install via pip

Install in a virtual environment (recommended)

Install from source

Configuration

API key setup

Optional: AI analysis keys

Optional: GitHub token

Full environment setup

Platform-specific notes

Upgrading

Uninstalling

Troubleshooting