CLI & Python API
Every command, flag and function in one place. cz is a short alias for contextzip, and -h works on every command.
Command builder
Toggle flags to compose a command and preview its output.
Live preview
$ contextzip
✓ Detected Next.js + Node.js · high confidence
✓ Scanned 2,752 files & Packed 44 files · 185 KB → 63 KB, ↓66% smaller
✓ Saved to · .contextzip/output/codebase/codebase.zip · snapshot #14 (k3f9a2)
✓ Ready to paste
Run flags
These work on contextzip, include and exclude, placed after the verb.
| Flag | What it does |
|---|---|
| -i, --include PATH | Only include files under these paths. Naming an excluded path brings it back. Repeatable. |
| -e, --exclude PATTERN | Extra exclusion patterns, gitignore syntax. Repeatable. |
| -p, --prompt TEXT | Let Gemini pick the files relevant to this task. |
| --git-changes | Only staged, unstaged and untracked files. Needs a git repository. |
| -n, --dry-run | Show what would be included; write nothing. |
| -o, --output FILE | Write the ZIP to this exact path, bypassing .contextzip/. |
| --no-clipboard | Don't put the ZIP on the clipboard. |
| --no-gitignore | Ignore .gitignore and use only the built-in rules. |
| -v, --verbose | List every included and excluded file. |
| --here | Only package the folder you're in. Paths stay relative to the project root. |
| --version | Print the installed version. |
Commands
contextzip
Details →Detect the stack, leave out the noise, package the project.
include
Details →Package only these paths. Naming an excluded path, like .env, brings it back.
exclude
Details →Package everything except these gitignore-style patterns. Quote patterns with * so your shell doesn't expand them.
apply-zip
Details →Put an AI-returned ZIP back into your project — matched, merged around your edits, reviewable side by side.
watch
Details →Run a command and package debug context when an error appears.
config
Details →Gemini key, workspace location and the visual config UI. No flags shows your current setup.
snapshots
Details →List the numbered snapshots apply-zip merges replies against.
update
Details →Check PyPI and upgrade in place, using whichever of pip, pipx or uv installed it.
Where files go
.contextzip/├── output/│ ├── codebase/ codebase.zip + .report.txt (latest only)│ ├── git-changes/ changes.zip + report│ ├── prompt/ vibe.zip + report│ └── watch/ debug-context.zip├── snapshots/ #1, #2, … — what you sent, kept for merging├── inbox/ drop AI-returned ZIPs here│ └── applied/ archived after apply-zip└── config.json project config (optional)Lives at your git root by default — see workspace location. Old outputs are cleaned up automatically.
Python API
Everything the CLI does is a plain function underneath — no Click, no Rich output, no SystemExit. Functions return objects and raise typed exceptions.
from contextzip import get_files, get_git_changes, create_zip, apply_zip # Every project file that passes the rules — plain pathlib.Path objectscollection = get_files(include=["src/"], exclude=["*.log"])for path in collection.files: print(path) # Only what changed, zipped (with a local manifest beside it)pkg = create_zip(get_git_changes(), output="/tmp/changes.zip")print(f"Packed {pkg.file_count} files -> {pkg.zip_path}") # Later: apply the ZIP an AI tool returnedresult = apply_zip()print(f"Wrote {len(result.written)} files")| Function | Returns |
|---|---|
| get_files(path=None, *, include, exclude, use_gitignore=True, use_project_config=True) | FileCollection of project files after the rules |
| get_git_changes(path=None, *, use_project_config=True) | FileCollection of staged, unstaged and untracked files |
| create_zip(collection, output=None) | PackageResult — zip_path, file_count, sizes, redacted, skipped_in_zip, snapshot |
| apply_zip(zip_path=None, *, project_dir=None, manifest=None, include_risky=False) | ApplyResult — written, skipped, removed, applied_zip_path, zip_kept |
| detect_ecosystem(path=None) | DetectionResult — the detected stacks |
All exceptions inherit from ContextzipError: NotARepositoryError, GitNotFoundError, GitCommandError, NoFilesError and ZipNotFoundError. Source and docstrings are on GitHub.