Files
poli0981andClaude Opus 5.5 2539950cd5 fix: what an independent review of 1.6.0 found
A venv made with --symlinks is run and stored as itself, not as the base
Python its python.exe links to: validate_interpreter returned the
canonical path, so `--env .venv update --all --yes` would have changed
the system Python. Canonicalizing now only decides where a link leads
and whether it is PipDock's own; a link to another program is refused,
and a Microsoft Store alias (os error 1920) is judged by its own path.

The GUI merges and removes an added row by its path rather than by
envHash, which follows links: a re-add replaces a broken row, removal
sticks for an entry whose file is gone (a share), and neither runs
during a scan. Added entries are validated again on every listing in
both heads (envs::probe_listed), and the CLI checks its stored default
when it uses it. `env remove` makes a typed path absolute first.

SECURITY section 2 and env_probe's doc claimed an enforcement point over
IPC; they now say what is checked, and backlog X36-b records the rest.
notify.yml reports a Triage failure on a pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00

192 lines
29 KiB
Markdown

# PipDock — CLI Specification
*Version 0.1 · 2026-07-17 · Binary: `pipdock` (clap, from `pipdock-cli` crate, same `pipdock-core` as the GUI)*
## 1. Principles
1. **Same core, same behavior.** Every CLI command maps 1:1 onto the core functions the GUI uses; the CLI adds no logic of its own.
2. **Safe by default, scriptable on request.** Interactive prompts appear on a TTY; in scripts (`--yes` / no TTY), a held-back package keeps its compatible version and an impossible one is **skipped** — never forced, unless `--strategy latest` asked for exactly that (§4). Off a TTY, a command that would ask first refuses instead unless `--yes` is given; `uninstall` and `pip-upgrade` ask nothing (§3).
3. **Machine-readable everywhere.** `--json` makes every command print one JSON document on stdout — the structs the GUI receives, wherever one exists (§6).
4. English-only in v1 (GUI carries EN/VI); messages reuse catalog codes so they stay greppable.
5. **Plain text, and nothing that moves.** No colour, no spinner, no progress bar, no line that rewrites itself with a carriage return: progress is whole lines on stderr, and `--quiet` drops them. This was true of the code since the first command and written nowhere, which is how a contract gets broken by someone adding a nicety. It is what makes the output readable by a screen reader, greppable in a log and the same in a pipe as on a terminal — so there is no `NO_COLOR` to honour, because there is no colour, and status is always a word (`ACCESSIBILITY.md`).
## 2. Global options
```text
--env <path> interpreter or env dir (default: the one `env use` set, else a venv in the CWD)
--engine <pip|uv> override configured engine for this invocation
--json one JSON document on stdout (§6); prompts, progress and warnings go to stderr
--yes / -y assume defaults on all prompts (held back → compatible, impossible → skip)
--quiet less on the terminal: no streamed engine output, no progress lines
--verbose the log on stderr as well, at DEBUG
--log-file <path> a copy of the log, appended to <path>
--no-snapshot DANGEROUS: skip pre-batch snapshot (CI images only; prints warning)
```
`--quiet` and `--verbose` cannot be combined (clap refuses it, exit 2). `--quiet` keeps the terminal to results, prompts, warnings and errors — `env use` and `tools sync` drop even their one-line confirmation — and changes nothing in the log. `--no-snapshot` applies to `install`, `update` and `uninstall`; `snapshot rollback` always snapshots the state it replaces (DATA-FLOW §8) and accepts the flag without acting on it.
**Which environment.** In order:
1. `--env` — an interpreter, or an environment directory whose `Scripts\python.exe` is used; refused with PD-ENV-001 unless it is named like a Python interpreter and outside PipDock's own venvs (SECURITY §2);
2. the default `pipdock env use` stored. If its interpreter is gone, stderr says `` warning: the default environment (<path>) no longer exists; `pipdock env use` sets another `` and the search goes on;
3. the first of `.venv`, `venv`, `env`, `.env` in the working directory that holds an interpreter.
Nothing found is PD-ENV-001 (exit 3), naming all three ways. Only `env use` writes the default — selecting an environment in the GUI does not change what the CLI acts on. `env list`, `info`, `index`, `tools` and `schema` never look for an environment; `search` and `self report-bug` use one when they find one and work without it; `engine` reports without one (§3). Until 1.4.0 the default was written and read by nothing, so `env use` reported success and every later command ignored it (X3).
**Logging.** Every invocation appends to `%LOCALAPPDATA%\PipDock\data\logs\pipdock-cli.<YYYY-MM-DD>.log` — one file per UTC day; the GUI writes `pipdock.<date>.log` beside it, so the two never interleave — and sweeps that folder of dated log files older than `LOG_RETENTION_DAYS` (14), leaving any other file alone. The file's level is `PIPDOCK_LOG`, a `tracing` filter directive such as `debug`, and INFO when it is unset or not a valid directive. At INFO the file holds the invocation's arguments, each subprocess's argv, exit code and duration, every stop and its reason, and each resolve, snapshot and run outcome; the lines an install, a removal or a tools-venv sync prints as it runs are DEBUG. `--verbose` adds stderr at DEBUG, whatever `PIPDOCK_LOG` says. `--log-file` appends the file's lines, at the file's level, to a path of your choosing; one it cannot open is a warning on stderr, not a failure. **Nothing is ever logged to stdout**, so `--json` stays one document under `--verbose`. An internal error (exit 10) prints `log: <today's file>` on stderr, in both modes. Until 1.4.0 there was no log at all: `tracing` was a dependency and never called, and `--verbose` and `--log-file` were parsed and ignored.
## 3. Commands
```text
pipdock env list # discovered envs, then the added ones; sources, PEP 668 flags
pipdock env use <path> # set the default env (§2)
pipdock env add <path> # add an interpreter or env dir to the list (the GUI's Add interpreter…)
pipdock env remove <path> # take an added one off the list; nothing on disk changes
pipdock list [--outdated] # installed packages, from the probe; --outdated asks the index
pipdock search <query> [--limit n] # local fuzzy index search (n defaults to 20)
pipdock info <pkg> # cached PyPI metadata
pipdock install <spec...> [--dry-run] # spec = a name, optionally with a PEP 440 specifier set; dry-run prints the ResolutionReport
pipdock update [--all | <pkg...>] # one or the other: neither is a usage error (exit 2)
[--strategy compatible|latest] # latest forces every held-back package, where nothing is asked (§4)
[--except <pkg,...>] # ad-hoc exclusions on top of pins; comma-separated or repeated
[--dry-run]
pipdock uninstall <pkg...> [--force] # guard names each dependent and its constraint; --force overrides; no prompt
pipdock pin add|remove <pkg> [--reason "…"] | pin list
pipdock snapshot list | create | diff <id> | rollback <id|latest>
pipdock doctor # the engine that would run + env sanity; exit 1 on real problems
pipdock audit # known advisories in the selected environment; exit 1 on findings
pipdock health [--path <dir>] [--tool deptry|vulture|ruff] [--fix] # --fix = ruff only, prompts
# --yes: proceeds on a clean tree,
# REFUSES on a dirty one (exit 2)
pipdock pip-upgrade # upgrade pip inside the selected env: always pip, no snapshot
pipdock engine [pip|uv] # no argument: both engines' versions; with one: set it
pipdock index refresh # re-pull PEP 691 name index
pipdock tools sync [--force] [--python <path>] # build/re-sync the Code Health tools venv
pipdock tools status # where it is, and whether it matches the shipped pins
pipdock schema <type> # JSON Schema for a core type, so scripts can pin against it (§6)
pipdock self report-bug # prints prefilled GitHub issue URL (ERROR-CATALOG §4)
```
**Specs.** `install` takes a name, optionally followed by a PEP 440 specifier set: `requests`, `django==5.0.1`, `"django>=5.0,<6"`, `"attrs ~= 23.1"`, `pkg===1.0`. An extra, a marker, a URL or anything else PEP 440 does not define is PD-PKG-002 (exit 1), refused before it reaches argv (SECURITY §2). `install --help` still says "`name` or `name==version`", which until 1.4.0 was the whole grammar: a request was split on `==`, so `django>=5.0,<6` became a package name.
**Before anything changes.** `install`, `update`, `uninstall` and `snapshot rollback` begin with a fresh probe of the environment, and three rules follow from it.
- *PEP 668* (SECURITY §3). An environment carrying the `EXTERNALLY-MANAGED` marker is refused with PD-ENV-002 (exit 3) before any engine command runs. The only way past is the GUI's Settings override, which the CLI reads from the store both heads share — **there is deliberately no CLI flag for it**: the override is meant to be hard to reach, and a flag would put it one shell-history search away. With the override on *and* the marker present, every mutating engine call is given `--break-system-packages`, and so is uv's dry-run resolve, which refuses a managed environment without it (pip's `--dry-run --report` never is). uv takes the flag in every version PipDock supports, pip from 23.0.1, which added it. Every such run says so on stderr: `warning: this Python is externally managed (PEP 668) and the Settings override is on, so --break-system-packages will be passed. Prefer a virtual environment.` pip 23.0 enforces PEP 668 with no way past it, so it is refused with PD-ENV-002 even then (`pip 23.0 enforces PEP 668 and has no override; --break-system-packages arrived in pip 23.0.1`); `--engine uv` gets through, and `pip-upgrade` does not help, because it refuses a managed environment whatever the override says. Below 23.0 pip enforces nothing and is passed nothing. A venv never carries the marker. Until 1.4.0 the override was saved and read by nothing, the gate trusted a cached flag rather than a probe, and a rollback had no gate at all.
- *Requires-Python* (hard invariant 10). PipDock enforces it itself, because the engines disagree: pip refuses an incompatible exact pin with the "No matching distribution" it gives a typo, and uv plans past an upper bound. An exact pin the user typed (`name==v`, `name===v`) is checked before any engine sees it; a release *Force latest* would install is checked before it is forced; and every release the engine planned is checked after. pip's report says what each planned release requires; for the rest — exact pins, forced releases, anything uv plans — PipDock asks PyPI (`https://pypi.org/pypi/<name>/<version>/json`), remembers each answer, and never blocks on one it cannot get. A planned release that excludes this interpreter is ruled out by name and the engine asked again, at most twice, so the engine rather than PipDock picks what comes next; one still planned after that stays in the plan, as a warning. Every such release is in the report's `incompatible` (§6), which the preview prints as *Left out — needs a different Python*; a request that is nothing but such pins fails with PD-PKG-001 instead (exit 1), naming the range and the interpreter's version. Until 1.4.0 nothing raised PD-PKG-001.
- *A preview is good for ten minutes, and for the environment it was made against* (DATA-FLOW §9.3). Between the decision and the snapshot — after the confirm, or after the guard for `uninstall` — the environment is probed again, or re-frozen for a rollback, and a preview older than ten minutes, or one the environment no longer matches, is refused with PD-RES-002 (exit 2). The refusal comes before the snapshot, so it costs nothing; re-run the command. Until 1.4.0 both checks existed and neither could fire.
**`uninstall` asks nothing.** The guard runs once over the whole removal set before anything is touched (DATA-FLOW §5). Clear, the packages are removed at once, after the snapshot. Tripped, the command refuses with PD-RES-004 and exit 2 and prints the `pipdock uninstall …` line that would remove the dependents too — unless `--force` was given, which prints `warning: --force given; proceeding despite the breakage above` and removes. `--yes` changes nothing here.
**`pip-upgrade`** always runs pip, whatever `--engine` or the configured engine says: there is no uv way to upgrade pip (DATA-FLOW §7). It asks nothing and takes no snapshot (DATA-FLOW §9's pip-upkeep exemption), refuses a PEP 668 environment whatever the override says, and falls back to `ensurepip` for a pip too broken to run — every pip below 22.2 on Python 3.12+.
**`doctor`** judges the engine that would run — `--engine`, else the configured one — and exits 1 when that engine is unavailable, or its check finds broken requirements or cannot run. Until 1.4.0 it required pip whatever was configured, which failed every uv-only venv (`uv venv` makes them without pip). Whether the Code Health tools venv is built is reported and never affects the exit.
**`audit`** checks the engine's freeze, so `--engine` decides what is audited: pip's `freeze --all` lists pip, setuptools and wheel, and uv's freeze does not. pip-audit runs from a venv of its own (`data\audit\`, built on first use; SECURITY §6) against PyPI's advisory service. Exit 1 on findings; a pip-audit that could not run exits on its problem's code instead (§5), so an empty report from a tool that never ran cannot read as clean. Until 1.4.0 it used the configured engine whatever `--engine` said.
**`engine`** with no argument reports both engines' availability and version, and needs no environment: uv is a standalone binary, and pip, a module of some interpreter, is reported unavailable without one. It does not say which engine is configured. With an argument it sets the configured engine — the setting the GUI shows — and refuses (PD-ENG-001) one that is not available here, because storing a preference that cannot be honoured moves the failure to the next command; setting pip needs an environment to look for it in. Until 1.4.0 the report failed in any directory without a `.venv`.
**`health --fix`** under `--yes` proceeds on a clean tree and refuses a dirty one (`error[PD-RES-002]: … uncommitted change(s) here; --yes will not rewrite files you have not committed. Commit or stash first.`, exit 2): the default over uncommitted work is *don't*, and the remedy is `git commit` or `git stash` rather than a flag. Outside a git repository, or without git, there is no tree to be dirty, and `--yes` proceeds. Off a TTY without `--yes` it refuses (exit 2), and `--fix` with a `--tool` list that leaves out ruff is refused before anything runs (`error[PD-PKG-002]: --fix needs ruff; it is the only tool that writes`, exit 2).
## 4. Interactive conflict handling (TTY)
`update`/`install` resolve, then ask about each held-back package before the preview is printed — on stderr, in both modes, like every prompt:
```text
requests held back at 2.30.0 (latest 2.32.3)
— apiclient 1.4 requires requests<2.31
[C]ompatible (default) [S]kip [F]orce latest:
```
`s` drops the package from this plan, and `f` forces its latest and names what that breaks (` this will break: apiclient`); anything else — Enter, `c`, even `skip` — keeps the compatible version. Any answer but *Compatible* re-resolves, and the questions repeat for whatever the new report holds back, for at most three rounds (`MAX_CONFLICT_ROUNDS`); after that the plan is confirmable as it stands. An impossibility is not asked about: its packages are skipped — and on a TTY, as the code stands, nothing says so, because the engine's explanation is printed only where nothing is asked (below). Then the preview, and the confirm, which is where a plan is abandoned:
```text
Apply 4 change(s)? [y/N]:
```
`y` or `yes` proceeds; anything else prints `aborted` and exits 2 — under `--json`, with the `ResolutionReport` as the document. `--dry-run` stops at the preview, but after the questions, because the decisions are part of what the report describes.
**With `--yes`, or without a TTY on stdin,** nothing is asked: a held-back package keeps its compatible version and an impossibility's packages are skipped. The impossibility is said first, on stderr — the engine's explanation, then `skipping: <names>` — so `every package was skipped` does not arrive unexplained. Off a TTY *without* `--yes` the confirm refuses rather than assuming: `error[PD-RES-002]: not a terminal; pass --yes to apply without confirming`, exit 2. (PD-RES-002 describes a stale preview; a code for "confirmation required" is the audit backlog's X17, ROADMAP.)
**`--strategy latest`** answers *Force latest* for every held-back package — only where nothing is asked, so with `--yes` or off a TTY. The report then carries `forced` (§6), and the preview a *Forced — will break* section naming each installed package whose requirement is overridden. On a TTY it changes nothing: each package is still a question, and Enter is still *Compatible*. Off a TTY nothing runs without `--yes` in any case, which makes `--yes` the "explicit acknowledgement" its help text describes; `--yes` without `--strategy latest` never forces. Under `--json --yes` no preview is printed at all, so a script that forces should read `forced` from a `--dry-run` first.
> **Corrected in 1.4.0.** This section said the preview came before the questions, offered an `[A]bort plan` answer, and had `--strategy latest` print its breakage warning before "a mandatory 3-second countdown (skippable with a second `-y`)". The binary has asked first since its first version, and has never had an abort answer — abandoning a plan is the final confirm's `N` — or a countdown; `--yes` is a bool, so there is no second `-y`, which `health --fix` already recorded. Nor did forcing force anything until 1.4.0: the decision was recorded in the request and no resolve read it.
## 5. Exit codes
| Code | Meaning |
|---|---|
| 0 | success, all steps ok — a dry run, a plan with nothing to change and `nothing-to-do` included |
| 1 | completed with per-package failures (see JSON `counts.failed`); **or `health` or `audit` found something** — a linter that exits 0 on findings is useless in a pre-commit hook, and `doctor` already uses this code for "found real problems"; or a failure coded PD-PKG-*, PD-BLD-*, PD-PRM-*, PD-SYS-* or PD-HLT-*, such as a malformed spec (PD-PKG-002) or a request this Python cannot install (PD-PKG-001) |
| 2 | plan aborted, nothing executed: resolution impossible and the skip policy removed everything (`everything-skipped`); uninstall guard tripped without `--force` (PD-RES-004); the confirm declined, or not askable — no TTY and no `--yes`; a stale or drifted preview (PD-RES-002); `health --fix` refused or declined; or a usage error — clap's own, `update` with neither names nor `--all`, `--fix` with a `--tool` list that leaves out ruff |
| 3 | environment error (PD-ENV-*, incl. PEP 668 block) |
| 4 | engine unavailable / version too old / stopped by its watchdog (PD-ENG-*) — outside a batch; inside one, a watchdog is a per-package failure (1) |
| 5 | snapshot failure — nothing was executed (PD-SNP-001); or no such snapshot (PD-SNP-002) |
| 6 | network/index error (PD-NET-*) |
| 10 | internal error (PD-INT-*); `log: <path>` on stderr, in both modes (§2) |
| 130 | stopped by Ctrl-C or Ctrl-Break during `install`, `update`, `uninstall` or `snapshot rollback`; see below |
An error's exit is derived from its code's area (`run::exit_for`) rather than written out per call site, so a new code cannot land on an undocumented number, and a test holds every code in `Code::ALL` to this table.
**Ctrl-C** — or Ctrl-Break, which a supervising process can send to one process group — during `install`, `update`, `uninstall` or `snapshot rollback` stops the run rather than the process. stderr says `stopping — press Ctrl-C again to quit now`, the flow's cancellation token trips, and the engine's whole process tree is killed (exec's job object). What completed is summarized — under `--json` the `ExecutionSummary`, with `"cancelled": true` — and stderr names the way back: `` stopped. What ran is above; `pipdock snapshot rollback <id>` puts back the state from before this run. `` Exit 130. Stopped during a resolve, nothing was planned or run: the document is `{"step":"nothing","reason":"cancelled"}`, stderr says `stopped before anything was planned; nothing ran`, exit 130. A **second** Ctrl-C exits 130 at once, with no summary, for a step that is not listening — a probe, a snapshot write. Every other command installs no handler, and Ctrl-C ends it the way it ends any console program: no summary, and not 130. Either way the engine's process tree goes with it. Until 1.4.0 that was true of every command, so Ctrl-C mid-batch printed nothing and said nothing about the snapshot just written (X6).
## 6. JSON contracts
**`--json` prints exactly one JSON document on stdout per command, and nothing else goes there.** Prompts, the preview shown before a prompt, warnings, progress prose and the engine's streamed output go to stderr — in both modes — and so does the log under `--verbose` (§2). Each document is the serde-serialized core type where one exists, the structs the GUI receives, pretty-printed; `pipdock schema <type>` prints the JSON Schema generated from the Rust type, so scripts can pin against it, and an unknown name lists the types it knows (PD-PKG-002, exit 1).
| Command | The document |
|---|---|
| `install`, `update` | The `ResolutionReport` when nothing runs — `--dry-run` or a plan with no changes (exit 0), a confirm declined or not askable (exit 2). The `ExecutionSummary` when something runs (0, 1 or 130). A `FlowStep` when there is nothing to plan: `{"step":"nothing","reason":…}` with `nothing-to-do` (0), `everything-skipped` (2) or `cancelled` (130) |
| `uninstall` | The `GuardReport` when the guard trips without `--force` (exit 2); otherwise the `ExecutionSummary`. With `--force`, the summary alone |
| `snapshot rollback` | The `RollbackPreview` when nothing runs — the environment already matches (0), or the confirm was declined or not askable (2); otherwise the `ExecutionSummary` |
| `snapshot create` | The new snapshot's `SnapshotMeta` |
| `snapshot list` | `[SnapshotMeta]` |
| `snapshot diff` | `Diff`, as a rollback with this engine would see it; the lines no index can restore are printed in text mode only |
| `env list` | An array, one object per discovered interpreter and then per added one (`source: "manual"`, 1.6.0): `interpreter`, `source`, `python`, `externallyManaged`, `hiddenUserSite`, `packages` (a count), `envHash`, `pipVersion` — or `interpreter`, `source` and `error: {code, message}` for one that could not be probed, without failing the rest |
| `env use` | The `PyEnv` that is now the default |
| `env add` | The added interpreter in the shape of one `env list` element, `source: "manual"`. When discovery also finds that interpreter, `env list` shows it under the discovered source and spelling instead, and the added entry waits unseen |
| `env remove` | `{interpreter, removed}` — `removed` is false when it was not on the list, which is not an error (exit 0) |
| `list` | `[Dist]`, from the probe; with `--outdated`, `[OutdatedDist]` |
| `search` | `[Hit]` |
| `info` | `{meta: PackageMeta, freshness: Freshness}` |
| `pin list` | `[Pin]` |
| `pin add` | The `Pin` written — always `"mode": "exclude"` |
| `pin remove` | `{pkg, removed}`; `removed` is false, and the exit still 0, when it was not pinned |
| `doctor` | `{interpreter, python, envHash, externallyManaged, hiddenUserSite, engines: {pip, uv}, check, toolsVenv: {path, need, manifest}}`; `check` is null when the check could not run |
| `audit` | `AuditReport` |
| `health` | `HealthReport`; with `--fix`, the `FixReport` alone when a fix ran — see below |
| `pip-upgrade` | `{before, after}`, each pip's `EngineInfo` |
| `engine` | `[EngineInfo, EngineInfo]`, pip then uv |
| `engine <pip\|uv>` | The `EngineInfo` of the engine just set |
| `index refresh` | `RefreshReport` |
| `tools sync` | `{"state": "fresh"}` when the venv already matched (without `--force`); otherwise the venv's manifest after the sync |
| `tools status` | `{path, need, manifest}` |
| `schema <type>` | The JSON Schema, printed with or without `--json` |
| `self report-bug` | `{url}` |
**A failure prints the envelope and only the envelope** — `{"code":"PD-ENV-001","message":"…","stderrTail":null}`, on one line, with the exit §5 gives its code; `stderrTail` is the engine's stderr tail when there was one. Without `--json` the same failure is `error[PD-ENV-001]: …` on stderr.
**What prints no document.** Usage errors — clap's own, `update` with neither names nor `--all`, `--fix` with a `--tool` list that leaves out ruff — say so on stderr and exit 2 with stdout empty. `health --fix` prints the `FixReport` alone when a fix ran, because the pre-fix report describes a state that no longer exists by the time the command returns; when no fix runs — nothing was safely fixable (exit 0 or 1, by the findings), or the fix was refused or declined (exit 2) — it prints nothing, the report having been withheld for a `FixReport` that never came. A second Ctrl-C (§5) exits wherever it is.
**What 1.4.0 added and removed.** `ResolutionReport` always carries `changes` and `heldBack`; `impossible` is omitted when there is none, and the three fields 1.4.0 added — `incompatible`, `forced`, `yanked` — when they are empty, so a report that needs none of them reads as it did, less `raw`. `incompatible` (PD-PKG-001) is what was left out because its `Requires-Python` excludes this interpreter — `{pkg, version, requiresPython, python}`, structured so a head can set the range against the version rather than print a sentence (hard invariant 4). `forced` is each package *Force latest* moves, in `heldBack`'s shape: `latest` is the version it is forced to, and `blockers` are the installed packages whose requirement it breaks — DISCLAIMER §2's *Will break* rows, before anything runs. `yanked` (PD-PKG-003) is each withdrawn release the plan would install, with upstream's `reason` when it gave one: a warning rather than a failure, since both engines install them — and only the JSON carries it, because the text preview does not print it. `raw` left the wire: it was pip's whole `--report` document, every package's README included, and nothing read it. In `ExecutionSummary`, a row's `from` is the version it moved from — until 1.4.0 always null, so every upgrade read as a fresh install — `check.ok` is true only when the post-run check **ran** and found nothing, with `check.error` carrying the code when it could not run (a case that used to read `ok: true`), and `cancelled` is §5's Ctrl-C.
> **Settled in 1.4.0.** This section promised NDJSON for the streaming commands — events matching the GUI's `plan-progress` payloads, "terminated by a final `summary` object" — and from 2026-08-12 recorded that no command emitted any. None ever did. What the binary printed instead was not one document either: `install` and `update` printed the `ResolutionReport` and then the `ExecutionSummary`, so `pipdock install x --json | ConvertFrom-Json` failed on the second; `uninstall --force` printed the `GuardReport` before its summary; `snapshot rollback` printed its preview as prose; and `engine`, `env use`, `pin add`, `pin remove`, `snapshot create`, `pip-upgrade` and `self report-bug` ignored `--json` altogether (X5). The rule is now one document per command, and the table above is the contract. `--help` still describes `--json` as "NDJSON for streaming commands"; that line is wrong.
`GuardReport.breaks` maps each package being removed to the installed packages that would break, and each of those carries the specifier that says so: `{"numpy": [{"pkg": "pandas", "version": "2.1.4", "constraint": "<2,>=1.26.0"}]}`. `constraint` is the **bare specifier tail** — the distribution name is the map key, so a caller joins the two halves itself; `version` is omitted when the graph does not know it, and `constraint` is empty for an unconstrained dependency. DATA-FLOW §5's dialog needs the specifier to say *"Removing X breaks Y (requires X>=1)"*, and a bare list of names tells the user what will break but not whether they can live with it.
`Dist.sizeBytes` is present only when it can be known: it is summed from the distribution's RECORD manifest, which `.egg-info` distributions do not have and which a PEP 660 editable install fills with its import shim rather than its sources. The field is **omitted** in those cases rather than reported as `0`, and it is always omitted on a `Dist` that came from `<engine> list` — neither engine reports a size. Where present it is a lower bound: uncompressed bytes as recorded at install time, excluding `__pycache__` written afterwards. `pipdock list`'s human table does not show it, as it already omits `requiresDist` and `requiresPython`.
## 7. Examples
```bash
# Nightly maintenance of a bot venv (task scheduler), safe strategy, log kept:
pipdock update --all --env C:\bots\scraper\.venv --yes --json --log-file C:\logs\pd.log > C:\logs\pd-summary.json
# Audit what an upgrade would do without touching anything:
pipdock update pandas numpy --dry-run --json | jq '.heldBack'
# Refuse-to-break uninstall in CI (exit 2 — plan aborted — if the guard trips):
pipdock uninstall legacylib --json || echo "dependents exist, aborting"
```
The log file holds log lines, not JSON; the summary is the document on stdout. `heldBack` is camelCase, like every key on the wire; this example used to say `.held_back`, which `jq` answers with `null`.