CLI & Python API reference.
Every option, every subcommand, every library function — in one place, for when you already know what you're looking for.
Main command
Run bare for a sensible default, or compose any of these flags. Every flag here is also accepted by the exclude and include subcommands, following the git/docker/cargo convention of flags after the verb.
| Option | Description |
|---|---|
| -p, --prompt TEXT | Describe your task in plain English — Gemini selects only the relevant files |
| -i, --include PATH | Only include files under this path (repeatable) |
| -e, --exclude PATTERN | Add exclusion patterns in gitignore syntax (repeatable) |
| --git-changes | Only include files reported by git as modified, staged, or untracked |
| -n, --dry-run | Preview what would be included without creating a ZIP |
| -o, --output FILE | Write ZIP to a custom path — bypasses the .contextzip/ workspace entirely |
| -v, --verbose | Show every included and excluded file, with sizes |
| --no-clipboard | Skip the clipboard / folder-open step after creating the ZIP |
| --no-gitignore | Ignore the project's .gitignore (use only built-in rules) |
| --version | Print the installed contextzip version |
| -h, --help | Show help for the current command |
Subcommands
contextzip exclude PATTERN…
Exclude specific files or patterns and package everything else. Patterns follow gitignore syntax; folders match with or without a trailing slash.
contextzip include PATH…
Package only the specified paths and skip everything else. Paths match as exact prefixes at directory boundaries — src matches src/index.ts but not src2/index.ts.
contextzip apply-zip [ZIP]
Write an AI-returned ZIP back into the project. Full detail on the classification and safety model in applying changes back.
| Option | Description |
|---|---|
| --manifest PATH | Diff against a specific manifest instead of auto-detecting the latest |
| -n, --dry-run | Preview what would change without writing anything |
| -v, --verbose | Show every file and its status |
| -y, --yes | Skip the confirmation prompt, even for risky changes |
contextzip watch -- COMMAND
Wrap a dev server and package a debug context on demand when an error appears. No additional flags — everything after -- is passed straight through to the wrapped command. Full detail in the terminal error watcher.
contextzip config
Manage API keys, workspace location, and the visual config UI. Full detail in configuration.
| Option | Description |
|---|---|
| --reset-key | Clear the stored Gemini API key and re-run the setup prompt |
| --set-workspace LOCATION | Set your personal default for where .contextzip/ lives |
| --reset-workspace | Clear your personal workspace location override |
| --show-key-path | Print the path to the config file and exit |
| --ui | Open a local browser UI to set include/exclude preferences visually |
Run with no flags to print current key status, workspace resolution, and the active project config.
Python API
contextzip is also usable as a library — every CLI capability is a plain function underneath. No Click, no Rich output, no SystemExit. Errors raise typed exceptions instead.
| Function | Description |
|---|---|
| get_git_changes(path?) | Modified, added, and untracked files from git |
| get_files(path?, include?, exclude?) | All project files after exclusion rules |
| create_zip(collection, output?) | Write a FileCollection to a ZIP archive, with a sidecar manifest |
| apply_zip(zip_path?, project_dir?, manifest?) | Apply an AI-returned ZIP back into the project |
| detect_ecosystem(path?) | Detect framework and confidence level |
from contextzip import get_git_changes, create_zip, apply_zip
# Get changed files and use them directly
collection = get_git_changes()
for f in collection.files: # plain pathlib.Path objects
upload(f)
# Or zip them and upload the archive
pkg = create_zip(collection, output="/tmp/changes.zip")
with open(pkg.zip_path, "rb") as f:
upload_to_s3(f)
# Later, apply a ZIP an AI tool returned
result = apply_zip()
print(f"Wrote {len(result.written)} files, backup at {result.backup_dir}")All functions default path to Path.cwd(). Typed exceptions include NotARepositoryError, GitNotFoundError, NoFilesError, ApplyError, and MultipleZipsFoundError — catch them individually instead of parsing exit codes.
Installation
Requires Python 3.9+.
pipx is recommended for CLI tools — it keeps contextzip isolated in its own environment.