Agent enablement

Most CLIs can be automated if you fight them. You find the undocumented flag that skips the wizard, you parse a table that was formatted for a human, and then a release changes the column widths and your script goes quietly wrong.

Pithy’s CLI is built the other way around, because the kit is agent-drivable by design rather than by accident. Humans and agents drive the same commands, and the machine path is the specified one rather than the escape hatch.

Three rules, and they hold everywhere.

1. Full flags. Nothing is prompt-only

Every value a prompt would ask for has a flag that supplies it. There is no question the CLI can ask that a flag cannot answer, and no command whose only path to a value is a human typing it.

Where a capability’s config option has no default, --set key=value supplies it, repeatably. That is not a workaround — an option with no default is the capability’s statement that the answer is yours to give, and --set is where you give it.

2. No required prompt

A run can be told it may not ask anything, three ways. PITHY_NONINTERACTIVE=1 forbids every prompt for the session, --no-input forbids them for one call, and --json forbids them implicitly, because a caller parsing one line is not reading a question. Any one of them forbids, and none can grant what another forbade. Without any of them, a prompt opens only when stdin and stdout are both a terminal.

PITHY_NONINTERACTIVE exists because a terminal does not prove a person is present. An agent harness that allocates a PTY and runs without --json used to reach a prompt and wait for an answer nobody would give. Set the variable once in the harness and no prompt waits.

What matters is what happens next, and it depends only on the question. A question with a default takes it, exactly as a piped run always has — pithy init scaffolds with the directory’s name. A question with no default refuses, and names the flag. It fails input/required, exit 2, with the flag that answers it and, when the set is known, every value that flag takes. It does not pick a value nobody gave.

$ pithy add auth --json
{"error":{"code":"input/required","status":400,"flag":"--with-prerequisites","message":"auth requires secrets and email, which api does not compose.","action":"Run `pithy add auth --worker api --with-prerequisites --json`, or compose them first: `pithy add secrets --worker api --json`, then `pithy add email --worker api --json`.","exit":2,"retryable":false,"fix":"pithy add auth --worker api --with-prerequisites --json"}}

That is the whole design decision, and it is worth stating plainly: composing capabilities nobody asked for is not a thing to do behind an adopter’s back, and reporting Done. on a project that cannot boot is worse. A prompt where there is somebody to ask, and a flag where there is not.

The same rule covers pithy init (which scaffolds with the flags it was given and writes no credentials) and pithy add --worker in a project with several Workers. A question only a person may answer is different again. A typed confirmation phrase — pithy provision --confirm for a production environment, --confirm-rollback, --confirm-reset — fails core/person_required, exit 5, when the run cannot ask. The action line still names the flag, for the person; the exit code tells an agent to stop and ask rather than try variations. A headless production provision happens only when a person wrote the phrase into the pipeline on purpose.

3. --json everywhere, one document, one object

Every command takes --json, except one. The payload goes to stdout; everything else — progress, warnings, the update notifier — goes to stderr, so a pipeline capturing stdout gets clean input and a readable log at the same time. A script, a CI job or an agent gets the payload as one compact line; a person at a terminal gets the same document indented. Set PITHY_JSON=compact in an agent harness that allocates a PTY, so every document stays on one line whatever the terminal says. Every payload carries schemaVersion, bumped only when a key is removed or retyped, so a parser can key on it and ignore keys it does not know.

A failure is one {"error": …} line on stderr, and the exit code says what to do next: 2 to fix the call, 3 to run something first, 4 to retry with backoff, 5 to stop and ask a person. The line carries the same exit, a retryable flag, and, when the cause is known, fix — one pithy command that rights it, runnable as written. Exit codes has the contract, including how a command that died partway through reports what it changed on the way.

The payload is documented per command, and the documentation is gated. A test in the kit reads every command page and holds it to naming every key that command’s --json payload emits. A key added without a docs line fails the build in front of whoever added it, which is what keeps the reference from drifting the way hand-written reference usually does.

The one exception

pithy remove is destructive, and it is manual and interactive only. Passing --json fast-fails with core/person_required, exit 5, before anything changes. --no-input and PITHY_NONINTERACTIVE=1 are refused the same way, because they say nobody is at the keyboard.

That is not an oversight to be worked around. Automated teardown of an environment is a real need and it has a real command — the pithy feature lifecycle, which creates and destroys ephemeral environments per branch and runs headless end to end. Removing a capability from a checked-in Worker is a different act, and it stays a deliberate one.

What this buys an agent

An agent driving this CLI can scaffold a project, compose capabilities, migrate, provision, deploy, and read back the state of every environment — without a screenshot, a browser, or a heuristic about when a command has finished.

What makes that work in practice:

  • pithy schema --json describes the CLI that is installed. Every command’s positionals and flags, with their types, defaults and values, the JSON Schema of its --json payload and of the error line, and whether it mutates, is idempotent and needs the network. It is served from the binary, so it answers for the version on this machine, not the one in an agent’s training data.
  • --dry-run plans before it changes anything. Fourteen commands take it — add, ui add, worker rename, worker sync, provision, migrate, deploy, upgrade, seed, setup, secrets rotate, feature prune, payments reconcile and workflow trigger — and every one plans in the same shape, with each file’s diff where the command knows the bytes. A dry run makes every refusal the real run makes, so a plan is never a promise the run cannot keep.
  • Idempotence. Every lifecycle command is safe to re-run. A second pithy add auth wires nothing new and says auth is already wired into <worker>.; a second pithy migrate prints Nothing to migrate.; pithy provision adopts a resource of the right name rather than creating a second one. An agent that loses track of what it already did can simply run the command again.
  • Errors carry the remedy, and every command a line names runs as written. Every failure has an action sentence and, when the cause is known, a fix an agent can run as written. Whatever a line names — an action, a skip reason, a note — carries the --worker a project with several Workers needs, by its apps/ directory, the --with-prerequisites and --set the command requires, and the flags your own run was given when it names that run again. A command that deletes something or runs against production is never a fix: the line names it and says it is a person’s decision.
  • A success says what it left required, as next. add, provision, deploy, upgrade, ui add and setup name the step a run left required — [{ command, why }], in order. The key is absent unless the step is required, so every next an agent sees is one it should act on.
  • What it found worth asking about is offers, not next. The same [{ command, why }] shape, for a step the person chooses: deploy offers pithy dashboard connect to a staging or production environment with no dashboard connection. An agent puts an offer to the person before it runs it. The key is absent unless the run established the fact behind it.
  • pithy doctor --json is one call for the whole state. What is composed, what is bound, what has drifted, what is not provisioned yet, and which of those are findings rather than steps not yet taken. Its failures list is the exit as data, each entry with its fix. It is the first thing to run when the model of the project and the project disagree.
  • The project tells its agent how to drive the CLI. pithy init writes a marked Pithy block into the project’s AGENTS.md — pithy schema --json, PITHY_JSON=compact, PITHY_NONINTERACTIVE=1, --dry-run first, which steps belong to a person, the describeRoute fields that make an app route an MCP tool (operation, tool, power), and how a person connects an agent to a deployed environment with pithy mcp connect, reads first — with the exit-code table under it. pithy upgrade keeps it current. The block is the only part of the file Pithy owns, and CLAUDE.md gets one line importing AGENTS.md.

Point your agent at these docs

The documentation is also available over MCP, so an agent can search and fetch these pages rather than guessing at flag names from its training data.

Search these docs from an agent has the URL and a config snippet per client.

ESC