Commands

Complete reference for all zap commands.

init

Initialize a new Python project with a virtual environment.

zap init [--python <version>]

Creates:

• .venv/ - Virtual environment
• zap.lock - Lock file
• pyproject.toml - Project configuration

Options:

append

Install one or more packages.

zap append <package>...

# Install from PyPI
zap append requests
zap append flask sqlalchemy pytest

# Install with version constraint
zap append "requests>=2.28"

# Install from git repository
zap append git=https://github.com/user/repo

# Install specific branch
zap append git=https://github.com/user/repo@main

# Install specific tag
zap append git=https://github.com/user/repo@v1.0.0

Packages are:

• Downloaded from PyPI or cloned from git
• Cached globally at ~/.cache/zap/
• Added to pyproject.toml

remove

Remove one or more packages.

zap remove <package>...

# Example
zap remove requests flask

sync

Install all dependencies from pyproject.toml.

zap sync

Use this after cloning a project or when pyproject.toml changes. Supports both PyPI packages and git dependencies.

install

Install packages from a requirements.txt file.

zap install -r <requirements.txt>

# Examples
zap install -r requirements.txt
zap install -r requirements/dev.txt

Supports:

• Standard package specifiers (requests>=2.28)
• Comments and inline comments
• Environment markers (pywin32; sys_platform == 'win32')
• Git URLs (git+https://github.com/user/repo)

run

Run a Python script in the virtual environment.

zap run <script.py> [args...]

# Examples
zap run app.py
zap run server.py --port 8080

list

List all installed packages.

zap list

# Output:
# Installed packages (3):
#   certifi 2024.2.2
#   requests 2.31.0
#   urllib3 2.2.0

python

Manage Python installations.

python install

Download and install a Python version from python-build-standalone.

zap python install <version>

# Install latest Python 3.12.x
zap python install 3.12

# Install specific version
zap python install 3.11.8

Python versions are installed to ~/.zap/python/ and can be used with zap init --python.

python list

List installed and available Python versions.

zap python list

# Output:
# Installed Python versions:
#   3.12.8  (~/.zap/python/3.12.8/bin/python3)
#
# Available for download:
#   3.13.1
#   3.12.8  (installed)
#   3.11.11
#   3.10.16

cache

Manage the global package cache.

# Show cache info
zap cache info

# Clear cache
zap cache clean

version

Show zap version.

zap version
zap --version

help

Show help message.

zap help
zap --help