Skip to main content

​
Requirements

RequirementMinimum versionNotes
Python3.8+3.11+ recommended
pip21.0+Ships with Python
OSLinux, macOS, WindowsWSL2 supported on Windows

​
Install via pip

pip install zenveil
Verify the installation: 
zenveil --version
# zenveil 1.0.0
Keep your global Python environment clean by using a virtual environment: 
python -m venv .venv
source .venv/bin/activate
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

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"

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

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"
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
If your company uses a custom CA bundle:
pip install --cert /path/to/company-ca.crt zenveil
Never use sudo pip. Instead, install to user scope:
pip install --user zenveil
Or use a virtual environment (recommended).