**AI disclosure.** PipDock was written with substantial help from Claude Opus 5 (Anthropic, via Claude Code), and the fact was only visible as a commit trailer. `docs/AI-DISCLOSURE.md` is the full statement — model, vendor, period, what it wrote (source, tests, debugging, the VI catalogue), what review actually meant, what was not delegated, and how to verify any of it from `git log`. 172 commits, 163 with the trailer. It also says the thing worth saying: a green suite was never sufficient. Thirty-four defects reached or nearly reached `main` and not one was caught by the suite that was green at the time. Three surfaces, because three different people look in three different places: the README for someone browsing the repo, `docs/` for someone reading the code, and the **About tab** for someone who installed the app and will never open GitHub. The last one needed keys in both catalogues. **`docs/CLI-GUIDE.md`.** CLI-SPEC is the contract; this is what you type. Written against `pipdock 1.0.0` by running every command rather than by reading the spec — which is how the exit codes in it were confirmed (`PD-ENV-001` really is 3, `schema` on an unknown type really is 1) rather than copied. That also turned up a defect: `self report-bug` printed **fourteen stray spaces** in the middle of a sentence, because a multi-line string literal keeps its source indentation. Nobody had read the output. Also: `About.png` -> `about.png` so the seven screenshots share one convention, and the About shot joins the README. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
11 KiB
PipDock CLI — a guide
docs/CLI-SPEC.md is the contract: every flag, every exit code, every JSON shape. This is the
guide — what you actually type, in the order you would need it.
Everything here was run against pipdock 1.0.0 on Windows. Where a number or a code appears, it
came out of a real invocation, not out of the spec.
Installing it
The installer puts pipdock.exe next to the GUI, in %LOCALAPPDATA%\PipDock\. PipDock does not
edit your PATH. Add that folder yourself if you want to type pipdock from anywhere:
$dir = "$env:LOCALAPPDATA\PipDock"
[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));$dir", 'User')
Open a new terminal afterwards — the current one keeps the old PATH.
pipdock --version
The two flags that apply to everything
--env <PATH> picks the interpreter. It accepts either the interpreter itself
(C:\proj\.venv\Scripts\python.exe) or the environment directory (C:\proj\.venv). Omit it and
PipDock uses the last environment you selected, falling back to a .venv in the working directory.
--json switches to machine-readable output. Streaming commands emit NDJSON — one JSON
document per line — so a long update can be consumed as it runs rather than at the end.
Two more worth knowing early:
-y/--yesassumes the default answer at every prompt. Conflicts resolve to skip, never to force. There is deliberately no flag that makes--yesmean "force latest".--engine pip|uvoverrides the configured engine for one invocation, without changing your setting.
Finding environments
pipdock env list
Discovery covers venvs in the working directory, the PEP 514 registry and the py launcher. Real
output on a machine with two registry Pythons:
[
{
"envHash": "06a8abde…",
"externallyManaged": false,
"hiddenUserSite": "C:\\Users\\you\\AppData\\Roaming\\Python\\Python314\\site-packages",
"interpreter": "C:\\Python314\\python.exe",
"packages": 352,
"pipVersion": "26.2.1",
"python": "3.14.7",
"source": "registry"
}
]
hiddenUserSite is not an error. PipDock reads a non-venv Python in isolated mode, which skips
the per-user site-packages directory — so its package count can be lower than pip list. The field
is non-null exactly when that applies, and null inside a venv. See CLI-SPEC §7.
venv_scan matches exactly four directory names: .venv, venv, env, .env. A virtual
environment called anything else is invisible to env list, and you have to name it with --env.
Make one the default so you can stop typing --env:
pipdock env use C:\proj\.venv
Looking before you touch anything
pipdock list
pipdock list --outdated
list is local and fast. --outdated asks PyPI for each package's latest release, so it is the
networked one — on a 352-package environment it is the slower of the two by a wide margin.
pipdock doctor
doctor checks the engine, the interpreter and the environment's sanity, and exits 1 when it
finds real problems rather than 0 with a warning. That is what makes it usable as a gate.
Updating
# Everything outdated. Pins still apply.
pipdock update --all
# Named packages only.
pipdock update requests urllib3
# See the plan, change nothing.
pipdock update --all --dry-run
Every mutating command runs the engine in dry-run first, prints what would change, takes a
snapshot, and only then executes. --dry-run stops after the first step.
When a version conflict appears
pipdock update --all --strategy compatible # default: take the resolver's compatible version
pipdock update --all --strategy latest # force the latest, breaking whatever depends on it
--strategy latest off a TTY requires an explicit acknowledgement — it will not silently break an
environment because a script passed --yes.
Excluding things for one run
pipdock update --all --except black,mypy
--except is additive on top of the pin list; it does not replace it.
Installing and removing
pipdock install requests
pipdock install "django==5.0.1"
pipdock install requests --dry-run
Specs are name or name==version. Names are validated against PEP 508 and versions against PEP
440 before they reach a command line — PipDock never builds a shell string, so there is nothing
for a crafted package name to escape into.
pipdock uninstall requests
Removal runs the reverse-dependency guard first. If something still needs the package, the command
stops and exits 2 rather than removing it. --force proceeds anyway, and prints what will
break before it does.
Pins
A pin excludes a package from bulk updates. It is per-environment.
pipdock pin add numpy --reason "pytorch build is pinned to this"
pipdock pin list
pipdock pin remove numpy
Pins are enforced at the plan boundary, not in the display layer — an update that would move a pinned package never reaches the engine.
Snapshots and rollback
A snapshot is taken automatically before every batch. You can also take one by hand:
pipdock snapshot create
pipdock snapshot list
pipdock snapshot diff <id>
pipdock snapshot rollback <id>
pipdock snapshot rollback latest
Two things worth knowing before you rely on this:
difflists entries a rollback cannot restore — editable installs and direct-URL installs. That is deliberate: they are excluded from the pin set and reported separately rather than silently dropped. Restoring an editable install means re-runningpip install -eyourself.- A rollback snapshots the current state first, so one rollback creates a second timeline
entry. The trigger label on each entry is how you tell them apart —
latestmoves twice.
Code Health
pipdock health
pipdock health --path C:\proj
pipdock health --tool ruff --tool vulture
pipdock health --fix
deptry, vulture and ruff run from PipDock's own isolated tools environment, never from the environment being inspected — so analysing a project never installs anything into it.
health exits 1 when it finds something. A linter that exits 0 on findings is useless in a
pre-commit hook, so this is the intended behaviour, not a failure.
--fix applies ruff's safe fixes only, and prompts first. It is the one operation in PipDock
that writes outside site-packages and %LOCALAPPDATA% — it rewrites your source. There is no
snapshot for it, because no snapshot in PipDock describes a source tree; your version control is
the safety net, and the confirm says so. It refuses entirely, before writing a byte, if any target
file cannot be written.
The tools environment is built on first use. To manage it directly:
pipdock tools status
pipdock tools sync
Two facts about the tools that are pinned by tests because the specs had them wrong: all three
exit non-zero on findings (vulture uses 3), and deptry reports a module name, not the
distribution that provides it — PIL, not pillow. deptry also cannot be told which environment
to compare against, which is disclosed wherever its findings are shown.
Search and metadata
pipdock index refresh
pipdock search hello
pipdock info requests
search runs against a locally cached PyPI name index (PEP 691) — no network per keystroke. The
index is around 864,000 projects and 42 MB on the wire; index refresh re-pulls it.
pip upkeep
pipdock pip-upgrade
Upgrades pip inside the selected environment, which PipDock is otherwise careful never to
modify without a plan. Worth knowing: every pip below 22.2 is broken on Python 3.12+
(distutils, pkgutil.ImpImporter), so the one case this command exists for is also a pip that
cannot run — it falls back to ensurepip, and decides by asking pip --version rather than by
matching a traceback.
Scripting it
Exit codes
Verified by running, not copied from the spec:
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | completed with per-package failures — see counts.failed in the JSON; or health/doctor found something |
| 2 | plan aborted, nothing executed (resolution impossible, or the uninstall guard tripped without --force) |
| 3 | environment error, including a PEP 668 block |
| 4 | engine unavailable or too old |
| 5 | snapshot failed — nothing was executed |
| 6 | network or index error |
| 10 | internal error; the log path is printed |
| 130 | cancelled (Ctrl-C); child processes are reaped and a partial summary is printed |
Code 5 is the one to special-case in CI: it means the snapshot could not be written, so PipDock refused to run the plan at all. Nothing changed.
Pinning against the JSON shapes
pipdock schema ResolutionReport
pipdock schema ExecutionSummary
pipdock schema HealthReport
schema prints the JSON Schema for a core type, generated from the same Rust definitions the
commands serialize — so a script can validate against it instead of guessing. An unknown type name
exits 1.
A CI-shaped invocation
pipdock update --all --env C:\proj\.venv --strategy compatible --yes --json
--yes with --strategy compatible never forces anything; a package that cannot be updated
compatibly is skipped and reported, and one failure does not abort the batch — you get
"13 successful, 2 failed" with a reason per package.
--no-snapshot exists and you almost certainly do not want it. It is the only documented
escape from the snapshot-before-mutation rule, it prints a warning, and it is there for throwaway
CI containers that have nothing to roll back to.
Isolating the store
Every path PipDock writes lives under %LOCALAPPDATA%\PipDock\data\. Point LOCALAPPDATA
somewhere else and you get a throwaway store — useful for testing a workflow without touching your
real index, settings or snapshots:
$env:LOCALAPPDATA = 'C:\tmp\pipdock-test'
pipdock env list
When something goes wrong
Every user-visible failure carries exactly one catalog code — PD-ENV-001, PD-NET-002, and so
on. docs/ERROR-CATALOG.md lists all 34, what causes each and what to do about it. The code is
stable; the message around it is localised.
pipdock --verbose --log-file pipdock.log update --all
pipdock self report-bug
self report-bug prints a prefilled GitHub issue URL carrying the version, OS and engine.
Nothing is transmitted — you open it, read what it filled in, and submit it yourself.
See also
- CLI-SPEC.md — the contract: exhaustive flags, JSON shapes, exit codes
- ERROR-CATALOG.md — all 34 codes and what to do about each
- SECURITY.md — threat model, PEP 668 policy, what PipDock connects to
- CODE-HEALTH-SPEC.md — how deptry, vulture and ruff are invoked