Reference

JSON output and scripting

Add --json and contextzip prints exactly one JSON object instead of terminal output. It never prompts, and the exit code matches: 0 when ok is true. It's what the VS Code extension, the MCP server and the website use.

--json

bash

contextzip --json --no-clipboardcontextzip --json -n --verbose                 # dry run: what would go in, and what wouldn'tcontextzip apply-zip reply.zip --json --dry-runcontextzip snapshots --json

It works on contextzip, include, exclude, apply-zip and snapshots. Every object has ok, command, version, warnings and log (each step), plus error when ok is false. The rest depends on the command:

Command	Fields
contextzip, include, exclude	mode, dry_run, project, remote (with --from), detection, files (counts, included_bytes, estimated_tokens, included_files), ai (with --prompt), zip (path, sizes, estimated_tokens, snapshot, redacted; null on a dry run), report, clipboard
apply-zip	project, plan (snapshot, remap, needs_decision, counts, files: path, source, status, safe, reason, moved_from…), result (written, skipped, removed, zip_kept, archived_to; null when nothing was written), report. With --pr: repository and pull_request.
snapshots	project, snapshots (id, token, label, mode, files, status, created)

apply-zip --json never asks: if a file needs a decision, nothing is written unless --safe-only, --yes or --review says what to do. When a remote repository can't be fetched, error_kind says why: invalid, not_found, private, too_big, rate_limited, auth or unavailable.

From Python

contextzip.web.run runs any command and returns its JSON result as a dict, without printing, prompting or exiting. It's how the website runs contextzip in the browser, through Pyodide.

python

from contextzip.web import run result = run(["--no-clipboard"], cwd="/path/to/project")print(result["zip"]["path"], result["zip"]["estimated_tokens"]) run(["apply-zip", "reply.zip", "--safe-only"], cwd="/path/to/project")

As a web service

contextzip.service.app is a WSGI app that packages public GitHub, GitLab and Bitbucket repositories: ?repo=github.com/user/repo returns the ZIP, and &format=json a summary. It checks with the host that every repository is public, caps downloads, rate-limits each client and never returns server paths. On Vercel, the whole function is:

api/pack.py

from contextzip.service import app