Files
pipdock/docs/CLI-GUIDE.md
T
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

25 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.

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:

$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 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.


Finding environments

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:

[
  {
    "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):

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:

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

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. 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.

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

# 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.

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

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

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.

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:

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:

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.

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:

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

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:

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

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

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. 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

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

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:

$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:

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 — 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.

See also