The contract
Driving the CLI from an agent is the worked session, driving your AI with docs is how it learns the flags, --json and exit codes is the machine surface, and the CLI is what a human reads.
Every command is agent-drivable and supports --json.
One deliberate exception: pithy remove is destructive, so it is manual and interactive-only. Passing --json fast-fails with a clear error before anything changes.
Its confirmations are typed at a real terminal, and there is no headless path. Automated teardown of an ephemeral environment is a different command — the feature lifecycle, not remove.
--json is one line, one object
Machine-readable, on stdout, and nothing else on it.
Color detection is decided once from the environment rather than by a library that reads any CI variable as color-capable — because our output is parsed, and a CI runner finding ANSI inside --json is the bug that produces.
The payload is specified where the command is
Every command page carries the same six sections — synopsis, flags, what it does, --json, errors, examples.
And a build gate holds each page to naming every key its command’s --json payload emits. A page that describes a payload it does not have fails the build rather than misleading an agent.
Ambiguity is refused, not guessed
A multi-Worker project prompts a human and raises an actionable error under --json rather than picking one.
Wiring a capability into the wrong Worker would put its bindings, its routes and its migrations somewhere nobody asked for — so the command stops and names what it needs.
The same rule holds for pithy dashboard connect: several Workers means --worker <name>, and a Worker composing no control plane is refused outright.
What is safe to run repeatedly
Every provision is idempotent — find-then-create, create-then-update, a deploy that overwrites. Re-running is a no-op.
pithy worker sync touches no account and runs no deploy. Safe on any branch, at any time, as often as you like. Running it twice changes nothing and writes nothing.
pithy migrate is a registry run, and a database already at the head is a no-op.
What needs a human
pithy remove, as above.
Production provisioning takes a type-to-confirm phrase that --yes never replaces.
A supplied secret — an OAuth client secret, a payment rail’s key — stops provisioning, because a random string there authenticates against nothing.
Nothing prints a secret
No minted value is printed, logged, or put in an audit event by any command.
Which matters most to an agent, because an agent’s transcript is a log, and a log is forever.
Exit codes mean something
Read the code, not the text. pithy doctor in particular distinguishes a step you have not taken yet from drift you should act on — a project with no domain and nothing provisioned is not red on day one, because turning the report red for everybody on day one teaches people to ignore it.