Files
poli0981andClaude Opus 5.5 957343c07b fix(core): a free-threaded python3.14t.exe is a Python too
Found by running env list against this machine: the python.org
installer puts python3.14t.exe (PEP 703) beside python.exe, the registry
lists it, and the new name rule refused it — so Add interpreter… could
not add an interpreter discovery itself reports. A version may now end
in t; pythonw3.14t, pythont and python3.14tt are still refused.

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

551 lines
25 KiB
Markdown

# 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.
Written by running `pipdock` on Windows, and kept to what the code does as the CLI changed: where a
number or a code appears, it came out of a real invocation or out of the code that produces it, 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:
```powershell
$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`.
```powershell
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 default you set with `pipdock env use`, falling back to a venv in the working
directory — `.venv`, `venv`, `env` or `.env`, in that order. Choosing an environment in the GUI
does not change what the CLI acts on.
**`--json`** switches to machine-readable output: **exactly one JSON document on stdout**, whatever
the command, so `pipdock install requests --json | ConvertFrom-Json` works. Prompts, warnings,
progress and the engine's own output go to stderr. A failure prints a one-line envelope instead —
`{"code":"PD-ENV-001","message":"…","stderrTail":null}`. Ignore `--help`'s "NDJSON for streaming
commands": no command has ever emitted NDJSON, and until 1.4.0 `install` and `update` printed two
documents — the preview, then the summary — which is exactly what made that pipe fail. CLI-SPEC §6
lists which document each command prints, and the few paths that print none.
Two more worth knowing early:
- **`-y` / `--yes`** assumes the default answer at every prompt: a held-back package keeps its
compatible version and an impossible one is skipped. `--yes` on its own never forces anything —
see `--strategy latest` below for what does. Off a terminal, a command that would ask first
refuses instead unless you pass it; `uninstall` and `pip-upgrade` never ask.
- **`--engine pip|uv`** overrides the configured engine for one invocation, without changing your
setting. `pip-upgrade` ignores it: upgrading pip is pip's job, whatever is configured.
The logging flags — `--verbose`, `--log-file`, `--quiet` — are under
[When something goes wrong](#when-something-goes-wrong).
---
## Finding environments
```powershell
pipdock env list
```
Discovery covers venvs in the working directory, the PEP 514 registry, the `py` launcher and
`uv python list`. Real output on a machine with two registry Pythons:
```json
[
{
"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 SECURITY §2.
**`venv_scan` matches exactly four directory names**: `.venv`, `venv`, `env`, `.env`. A virtual
environment called anything else is not discovered — name it with `--env` for one command, or put
it on the list for good (the GUI's *Add interpreter…* writes the same list):
```powershell
pipdock env add D:\work\scraper\myenv
```
It appears in `env list` after discovery's own rows, with `source: "manual"`, and in the GUI's
Environments screen. `pipdock env remove D:\work\scraper\myenv` takes it off again; nothing on disk
is touched, and its pins and snapshots stay for the day it comes back. Since 1.6.0 a path you give
`--env`, `env use` or `env add` must be named like a Python interpreter (`python.exe`,
`python3.exe`, `python3.12.exe`, the free-threaded `python3.14t.exe`) and must not be one of
PipDock's own venvs, or it is refused
with PD-ENV-001 before anything runs it.
Make one the default so you can stop typing `--env`:
```powershell
pipdock env use C:\proj\.venv
```
Every later command acts on it — `--env` still wins for one invocation, and the working directory's
venv is only the fallback. If its interpreter goes away, commands say so on stderr and fall back to
the working directory's venv. Until 1.4.0 `env use` stored the default and nothing read it.
---
## Looking before you touch anything
```powershell
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.
```powershell
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. The
engine it judges is the one that would run — `--engine`, else your configured one — so a uv-only
venv (`uv venv` makes them without pip) passes under uv. Whether Code Health's tools environment
has been built is reported, and never fails it.
```powershell
pipdock engine
pipdock engine uv
```
`engine` shows both engines and their versions, and needs no environment — without one, pip, which
lives inside an interpreter, reads `no environment selected`. It does not say which engine is
configured. `pipdock engine uv` sets it, and refuses an engine that is not installed.
---
## Updating
```powershell
# 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
```
`update` and `install` run the engine in dry-run first, ask about any conflict, print what would
change and ask once more; only then do they check that the preview still describes the
environment, take a snapshot and execute. `--dry-run` stops at the preview. `pipdock update` with
neither names nor `--all` is a mistake rather than an empty plan, and exits 2.
A preview is good for **ten minutes**, and for the environment it was made against. Confirm later
than that, or after something else changed the environment, and the run is refused with
`PD-RES-002` (exit 2) before the snapshot is written — nothing has happened; re-run the command.
### When a version conflict appears
On a terminal, each held-back package is a question — *Compatible* (the default), *Skip* or *Force
latest* — asked on stderr before the preview, with the installed packages holding it back.
CLI-SPEC §4 has the exact prompt. An impossible set is never a question: its packages are skipped,
and with `--yes` or off a terminal the engine's explanation is printed on stderr first.
```powershell
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` forces only where nothing is asked — with `--yes`, or off a terminal. Then every
held-back package goes to its latest, and the preview's *Forced — will break* section names each
installed package that stops being satisfied, with the requirement of its that is overridden. On a
terminal it changes nothing: each package is still a question, and Enter still means *compatible*.
Off a terminal nothing runs without `--yes` anyway, so for a script the acknowledgement *is*
`--yes` — and under `--json --yes` no preview is printed at all, so read `forced` from a
`--dry-run --json` first. Until 1.4.0 forcing forced nothing: the decision was recorded and the
resolve ignored it.
Updating one package on its own can hold it back with no culprit — the preview says *(nothing
installed explains this)* — when its new release needs a newer version of one of its own
dependencies, because a selective update keeps every package it does not name where it is.
`update --all` is unaffected, and `--strategy latest` works around it (ROADMAP's audit backlog,
BL-1).
### Excluding things for one run
```powershell
pipdock update --all --except black,mypy
```
`--except` is additive on top of the pin list; it does not replace it. It takes a comma-separated
list, and can be repeated.
---
## Installing and removing
```powershell
pipdock install requests
pipdock install "django==5.0.1"
pipdock install "django>=5.0,<6"
pipdock install requests --dry-run
```
A spec is a name, optionally followed by a PEP 440 specifier set — a range included. Extras,
markers and URLs are refused (`PD-PKG-002`). `--help` still says `name` or `name==version`, which
was the whole grammar until 1.4.0. Names are validated against PEP 508 and specifiers 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.
```powershell
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, and prints the `pipdock uninstall` line that would
remove the dependents too. `--force` proceeds anyway, and prints what will break before it does.
**There is no confirm prompt:** when nothing depends on the package, it is removed at once, after
the snapshot.
### When a release needs a different Python
PipDock checks `Requires-Python` itself, because the engines disagree: pip refuses an incompatible
exact pin with the same "No matching distribution" it gives a typo, and uv plans past an upper
bound and fails later, building from source. On Python 3.14:
```powershell
pipdock install scipy==1.7.3 # PD-PKG-001, exit 1: nothing else was asked for
pipdock install scipy==1.7.3 six==1.17.0 # plans six; scipy is listed as left out
```
The preview's *Left out — needs a different Python* section — `incompatible` in the JSON — names
the release, the range it requires and the Python you have. An update does the same for what the
engine planned: a release that excludes your Python is ruled out and the engine asked again, so it,
not PipDock, picks what comes next. Where the engine does not say what a release requires, PipDock
asks PyPI and remembers the answer; one it cannot get never blocks.
---
## Externally managed Pythons (PEP 668)
A Python marked `EXTERNALLY-MANAGED` by whoever installed it — a uv-managed CPython, for one — is
refused by `install`, `update`, `uninstall` and `snapshot rollback` with `PD-ENV-002`, **exit 3**,
before any engine command runs, and by `pip-upgrade` too. The answer is a virtual environment: a
venv never carries the marker, even one built from such a Python.
There is an override, in the GUI's Settings, and **deliberately no CLI flag**: a flag would put it
one shell-history search away. The CLI reads the setting the GUI stores. With it on, and only for
an environment that carries the marker, PipDock passes `--break-system-packages` — and every run
says so on stderr:
```text
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.
```
uv takes the flag; pip has since 23.0.1. **pip 23.0 itself is refused** with `PD-ENV-002` even with
the override, because it enforces PEP 668 and has no flag to get past it — and `pip-upgrade` cannot
rescue it, since it refuses a managed environment whatever the setting says. Use `--engine uv`, or
upgrade pip outside PipDock. Below 23.0 pip does not enforce the marker, and nothing is passed.
Until 1.4.0 the override was a checkbox nothing read.
---
## Pins
A pin keeps a package out of every update — one that names it as well as `--all` — until it is
unpinned. It is per-environment.
```powershell
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: a pinned package is taken out of
the request before the engine is asked. The text output says what was left out
(`1 pinned package(s) excluded: numpy`); under `--json` that line is not printed, so a script reads
`pin list --json`.
---
## Snapshots and rollback
A snapshot is taken automatically before every batch. You can also take one by hand:
```powershell
pipdock snapshot create
pipdock snapshot list
pipdock snapshot diff <id>
pipdock snapshot rollback <id>
pipdock snapshot rollback latest
```
`rollback` shows what it will remove and restore, and asks first — `--yes` skips the question, and
off a terminal it refuses without one. Like any change it is refused for an externally managed
Python, and refused with `PD-RES-002` if the environment changed between the preview and your
answer, or the answer took more than ten minutes.
Three things worth knowing before you rely on this:
- **`diff` lists 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-running `pip install -e` yourself.
- **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 — `latest` moves twice.
`--no-snapshot` does not apply here.
- **`diff` compares the way a rollback with the current engine would.** uv's freeze never lists
pip, setuptools or wheel, so across engines those three are left out of the comparison, and a
rollback never removes pip. Until 1.4.0 a uv snapshot restored with pip uninstalled pip.
---
## Code Health
```powershell
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.
It fixes exactly what the report looked at, with the same exclusions; until 1.4.0 it ran without
them, and rewrote notebooks and, in a project that sets its own `exclude`, files under `.venv`. With
`--yes` it proceeds on a committed tree and refuses, exit 2, on one with uncommitted changes —
commit or stash first. Outside a git repository there is no tree to check, and `--yes` proceeds.
Under `--json` it prints the `FixReport` alone, and nothing at all when no fix ran.
The tools environment is built on first use. To manage it directly:
```powershell
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.
---
## Security advisories
```powershell
pipdock audit
pipdock audit --engine pip
```
`audit` checks the environment's installed releases against PyPI's advisory data with pip-audit,
run — like Code Health's tools — from an environment of PipDock's own, never from the one being
checked; the first run builds it. It has no flags of its own. **It exits 1 when it finds an
advisory**, like `health`. A pip-audit that could not run at all exits on its own error code
instead, because an empty list from a tool that never ran must not read as "nothing wrong".
What it checks is the engine's freeze, so `--engine` matters: pip's lists pip, setuptools and
wheel, and uv's does not. Until 1.4.0 `audit` used the configured engine whatever `--engine` said.
Findings are grouped under each package and version: an advisory's id, its fix — `fixed in …`, or
`no fix` — and its aliases. There is no severity, because pip-audit publishes none (SECURITY §6).
`audit` changes nothing; the remedy is an ordinary `pipdock update <pkg>`.
The cost is a network fetch, not the package count: measured at 68 s cold, and about 20 s warm for
one package or twelve — which is why it says how many packages it is checking before the wait
rather than after it.
---
## Search and metadata
```powershell
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
```powershell
pipdock pip-upgrade
```
Upgrades pip **inside the selected environment**, which PipDock is otherwise careful never to
modify without a plan. It always uses pip, whatever `--engine` says — there is no uv way to upgrade
pip — and it asks nothing and takes no snapshot: a snapshot's only restore path would be pip
itself. It refuses an externally managed Python whatever the Settings override says. 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
| Code | Meaning |
|---|---|
| 0 | success — a dry run, and a plan with nothing to do, included |
| 1 | completed with per-package failures — see `counts.failed` in the JSON; **or `health`, `audit` or `doctor` found something**; or a failure coded `PD-PKG`, `PD-BLD`, `PD-PRM`, `PD-SYS` or `PD-HLT`, such as a malformed spec |
| 2 | nothing executed: resolution impossible, the uninstall guard tripped without `--force`, the confirm was declined (or there was no terminal to ask on and no `--yes`), the preview had gone stale, or a usage error |
| 3 | environment error, including a PEP 668 block |
| 4 | engine unavailable or too old, or an engine query stopped by its watchdog |
| 5 | snapshot failed — **nothing was executed**; or no such snapshot |
| 6 | network or index error |
| 10 | internal error; `log: <path>` follows on stderr |
| 130 | stopped by Ctrl-C during `install`, `update`, `uninstall` or `snapshot rollback`: the engine's process tree is killed, what ran is summarized, and stderr names the snapshot to roll back to. A second Ctrl-C quits at once |
Until 1.4.0 this table said it had been verified by running, and two of its rows were not true:
there was no log for code 10 to point at, and the CLI installed no Ctrl-C handler, so Ctrl-C killed
it outright — no summary, and no 130. Both rows describe the code now. Ctrl-C during any other
command still ends it the way it ends any console program, without a summary; the engine's process
tree goes with it either way.
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
```powershell
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, and lists the names it knows. Which document each command prints is CLI-SPEC §6's table.
### A CI-shaped invocation
```powershell
pipdock update --all --env C:\proj\.venv --strategy compatible --yes --json
```
`--yes` with `--strategy compatible` never forces anything: a held-back package takes its
compatible version, a package that cannot be updated at all is skipped — and named on stderr — and
one failure does not abort the batch: you get `"13 successful, 2 failed"` with a reason per package.
Its stdout is one document, the `ExecutionSummary` when anything ran. Test `$LASTEXITCODE` before
reading it: exit 0 is also *nothing to do*, which prints a `FlowStep` —
`{"step":"nothing","reason":"nothing-to-do"}` — instead.
**`--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. It covers `install`, `update` and `uninstall`;
`snapshot rollback` snapshots the state it replaces regardless.
### Isolating the store
Everything PipDock keeps for itself — the store, snapshots, the tools and audit environments, the
log — 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:
```powershell
$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 35 (in 32 rows: `PD-HLT-001..004` share one), what causes
each and what to do about it. The code is stable; the message around it is localised.
Every run is logged, whether you ask or not: one file a day,
`%LOCALAPPDATA%\PipDock\data\logs\pipdock-cli.<date>.log`, beside the GUI's `pipdock.<date>.log`,
kept for 14 days. It records what PipDock ran — the arguments you gave, every command it spawned
with its exit code and duration, each resolve, snapshot and run outcome — and nothing in it is sent
anywhere. When you want more:
```powershell
pipdock --verbose --log-file pipdock.log update --all
$env:PIPDOCK_LOG = 'debug'; pipdock update --all
pipdock self report-bug
```
`--verbose` shows the log on stderr as it happens, at DEBUG, which includes every line an install
or a removal printed. `--log-file` appends a copy at the file's level — set `PIPDOCK_LOG` as well if you want
DEBUG in it — wherever a CI job can collect it. Neither ever writes to stdout, so `--json` output
stays one document; `--quiet` only quiets the terminal. An internal error (exit 10) ends with
`log: <path>` on stderr. Until 1.4.0 there was no log at all, and `--verbose` and `--log-file` were
accepted and ignored.
`self report-bug` prints a prefilled GitHub issue URL carrying PipDock's version, the OS, the
engine, and the selected environment's Python and engine versions. It attaches no log excerpt:
attach the day's log yourself, after reading it for paths you would rather not make public.
**Nothing is transmitted** — you open it, read what it filled in, and submit it yourself.
---
## What is GUI-only
These have **no CLI surface yet**, and that is deliberate rather than an oversight — each would add
a subcommand and churn the help goldens for something nothing scripts against today. The logic
lives in `pipdock-core` (`pins::suggest`, `requirements::parse`, `cache::usage`,
`ReverseDeps::view`), so adding one later is small:
| Feature | Where it is | Nearest CLI equivalent today |
|---|---|---|
| Pin suggestions | Pins screen | none — `pin list` shows what you have pinned |
| Requirements export | Environments → *Open* | `snapshot create`, then read the `.freeze.txt` |
| Requirements import | Environments → *Open* | `install` with the specs, ranges included, which is what import does anyway |
| Disk usage | Settings | `tools status` reports the tools venv; nothing reports sizes |
| Dependency view | a package row's `⇄` | `list --json` carries each package's `requiresDist`, which the view is drawn from; `doctor` reports requirements the engine's check finds broken |
| Command palette | `Ctrl+K` | not applicable |
If you want one of these on the command line, say so in an
[issue](https://github.com/poli0981org/pipdock/issues) — the core function is already there.
**The PEP 668 override is GUI-only for a different reason, and stays so.** It is meant to be hard
to reach — a decision made in the GUI, behind a confirm — and a flag would put it one shell-history
search away. The CLI reads the setting the GUI stores, and says so on stderr every time it applies;
see [Externally managed Pythons](#externally-managed-pythons-pep-668).
## See also
- [CLI-SPEC.md](CLI-SPEC.md) — the contract: exhaustive flags, JSON shapes, exit codes
- [ERROR-CATALOG.md](ERROR-CATALOG.md) — all 35 codes and what to do about each
- [SECURITY.md](SECURITY.md) — threat model, PEP 668 policy, what PipDock connects to
- [CODE-HEALTH-SPEC.md](CODE-HEALTH-SPEC.md) — how deptry, vulture and ruff are invoked