The CLI is the product. There is no console you have to open, no wizard that owns a step, and nothing you can do in a dashboard that you cannot do from a terminal — which is also why an agent can drive the whole kit without a single screenshot.
This page is what every command shares. What one command does is on its own page.
The shape
pithy <command> [subcommand] [args] [--flags]Verb first, noun second, and the binary is always pithy:
pithy init
pithy add auth
pithy worker add admin-api
pithy migrate --env staging
pithy deploy --env prodFlags every command honors
| Flag | Meaning |
|---|---|
--json | One JSON document on stdout. Also forbids every prompt |
--pretty / --no-pretty | With --json, indent the document and color it, or keep it on one line. Refused without --json |
--no-input | Forbid every prompt for this call, without --json |
--help, -h | Help for any command |
--version, -v | The installed version, from anywhere before a -- separator |
--events works on deploy and provision only, and needs --json: it turns the one document into a stream of progress records closed by that document.
Long flags are kebab-case, short flags are a single letter, booleans default to false, and a value passes with either = or a space — --env=prod and --env prod are the same thing.
--version works after a subcommand as well as before one. That is deliberate: citty, the framework underneath, answers its own version builtin only when it is the sole argument, so pithy add --version would have run add instead. The rule lives in one place and applies everywhere.
A flag the command does not declare is refused, on every command. pithy doctor --bogus-flag yes exits 2 with Unknown flag: --bogus-flag. and, under it, the flags pithy doctor does take. Under --json the refusal is the one { "error": … } line on stderr — validation/invalid_input, one issue per flag — and nothing on stdout.
It is checked once, before anything answers the invocation: before citty, which would parse the flag without a word, and before --version, which would print over it. A flag is the command’s wherever it is typed, before its positional or after it, so pithy secrets rotate API_KEY --dry-rn is refused exactly as pithy secrets rotate --dry-rn API_KEY is. A group declares no flags of its own, so pithy token --json is refused rather than answered with usage. Declares means what pithy schema --json publishes for that command: each argument’s name, its camelCase spelling, its aliases, --no-<name> on a boolean, and the flags above that work everywhere. A declared string flag takes the next token as its value even when it starts with a dash; anything meant for a child process goes after --.
--json, and who is reading it
--json formats for whoever is reading it. A script, a CI job or an agent gets one compact line; a person at a terminal gets that same document indented two spaces, with restrained color. Nothing about the payload changes, so both parse to the same value. Which one you get is decided in this order, first match wins:
| Step | Signal | Effect |
|---|---|---|
| 1 | PITHY_JSON=compact or PITHY_JSON=pretty | Forces it for the whole session. Any other value is refused |
| 2 | --pretty / --no-pretty | Forces it for this call |
| 3 | Whether the stream is a terminal | A terminal is indented; a pipe, a redirect or a capture is one line |
The variable comes first because a terminal is not proof a person is reading. Agent harnesses and some CI images allocate a PTY, and every one of them would otherwise receive multi-line JSON. PITHY_JSON=compact settles it once. Each stream answers for its own reader, so pithy doctor --json > out.json at a terminal writes a compact document to the file and prints a readable error to the screen. A stream that is not a terminal is never colored.
A stream is never reshaped. pithy dev, pithy dev logs and --json --events write one compact object per line, at a terminal or not, because a consumer reading line by line cannot take { as a first line.
Every payload names the version of its shape, as schemaVersion. An integer per command, from 1, on every line a command writes. It is bumped only by a change that breaks a parser — a key removed or retyped. An added key does not bump it.
Runs that may not ask
PITHY_NONINTERACTIVE=1 forbids every prompt for the session, --no-input forbids them for one call, and --json forbids them implicitly. Any one of them forbids, and none can grant what another forbade. With none of them, a prompt opens only when stdin and stdout are both a terminal.
- A question with a default takes it, exactly as a piped run always has.
- A question with no default fails
input/required, exit 2, naming the flag that answers it and, when the set is known, every value it takes. - A question only a person may answer fails
core/person_required, exit 5: a typed confirmation phrase,remove --drop, andpithy removeitself under--no-inputorPITHY_NONINTERACTIVE=1. The action line names the flag for the person; the exit code tells an agent to stop and ask.
One confirmation is the deliberate exception. pithy token forget, when it cannot read whether the token has been used, asks at a terminal and drops the local copy when nobody can be asked. The token stays live, nothing on the account changes, pithy token rotate recovers an unwanted drop, and a token Cloudflare reports as never used is refused rather than asked about.
--dry-run plans, in one shape
Fourteen commands take --dry-run — add, ui add, worker rename, worker sync, provision, migrate, deploy, upgrade, seed, setup, secrets rotate, feature prune, payments reconcile and workflow trigger — each described the same way: Show the plan and write nothing. A dry run makes every refusal the real run makes before it plans anything, because a plan for a run that would be refused is a promise nobody can keep. Its text output ends with a line that opens Dry run. in place of Done.
Under --json each carries dryRun, and under --dry-run a plan with six lists, every one always present: files (with a diff wherever the command knows the bytes), resources, migrations, secrets, data and notes. A dry run writes nothing, and calls nothing that writes. add, ui add and worker sync make their writes in a private copy of the project and plan the difference, so the diff you review is the bytes the run writes.
next: what a success left required
Six commands can finish a run that still needs a step before it works, and under --json each names that step as next: [{ command, why }], in order, each command runnable as written. The key is absent unless the step is required, never an empty list, so every next you see is one to act on.
| Command | next names | When |
|---|---|---|
add | pithy provision --env <env> --yes, else pithy migrate --env <env> | An environment a provision had readied gained a binding without an id; else a provisioned environment has migrations it has not applied |
provision | pithy deploy --env <env> | A Worker it named has no deployed script on the account |
deploy | pithy migrate --env <env> | The environment’s databases have not applied every migration. Deploy never migrates |
upgrade | pithy migrate --env <env>, or the project’s own CLI’s upgrade | It counted pending migrations and did not run them; or it moved @pithy-sh/cli and left the reconcile to the new one |
ui add | The project’s install, <pm> install | It wrote dependencies into the Worker’s package.json, or for react-native into the app’s |
setup | pithy dev | Every real run. Setup starts nothing, so the Workers are not running until pithy dev runs them |
A step only a person may take is never named: provisioning production needs its --confirm phrase, so add names no step for it.
offers: what a success found worth asking about
A run can also find a step worth putting to you that it did not require. Under --json that is offers: [{ command, why }] — the same shape as next, each command runnable as written — and a different promise: an agent asks the person before it runs an offer, and runs a next without asking. Two keys rather than one, because a list an agent has to judge item by item is the thing next exists to never be. Like next, it is absent unless the run established the fact behind it, never an empty list, and carried by no --dry-run and no failed run.
| Command | offers names | When |
|---|---|---|
deploy | pithy dashboard connect --env <env> --worker <name>, once per Worker that composes the control-plane seam. Any one connects the project. The connection’s purpose is the person’s words, so the command cannot carry it: at a terminal it asks, and why says a run that cannot ask adds --purpose with their answer | A named environment — not dev, not a feature environment — deployed with no failure and has no dashboard connection. A connection registry that would not read offers nothing |
--env, and why it is short
--env takes dev, staging, or prod. It defaults to dev, because every command is safe there. It is validated at the flag, before anything loads.
It is not production. The environment sits verbatim in the middle of every Cloudflare name the project composes — <project>-<env>-<thing> — so each of its characters costs one character of project name, one for one. --env production is answered with an error naming prod.
A custom environment is allowed: live, eu-prod. It is held to the same character set and to a hard maximum of seven characters, the length of staging. Every project-name budget is derived against that seven, and a provisioned project cannot be renamed, so a longer environment is refused rather than quietly shrinking a cap other projects were already accepted under.
Which environments a project has is declared once, as environments in the root pithy.config.ts — ["staging", "prod"] unless it says otherwise. A command that deploys or provisions refuses an --env the project does not declare, and names the ones it does. dev is never declared, because it is local and always there.
--worker, and when you need it
Every Worker lives in apps/<name>/ and owns its own config. There is no root Worker.
- Commands that wire one Worker take
--worker <name>:add,remove. In a single-Worker project the flag is optional. In a project with several, the CLI prompts when the run may ask, and otherwise failsinput/required, naming--workerand every Worker it takes, rather than guessing — wiring a capability into the wrong Worker puts its bindings and its Durable Object class migrations on the wrong script. - Commands that operate on the project fan out over every Worker and accept
--workerto narrow:migrate,seed,upgrade,doctor,env,backup,restore.
Two Workers share a resource by declaring the same binding name, unless one owns it. Two Workers that both declare DB are backed by one D1; a Worker that wants its own lists DB in ownBindings in its pithy.worker.jsonc (naming).
One command refuses --json
pithy remove is destructive, so it is manual and interactive only. Passing --json fast-fails with core/person_required and exit 5 before anything changes, and its --drop confirmations are typed at a real terminal. --no-input and PITHY_NONINTERACTIVE=1 are refused the same way, because they say nobody is at the keyboard. There is no headless path, on purpose.
Automated teardown of an ephemeral environment is a different command — the pithy feature lifecycle — rather than a flag on this one.
The p. shortcut
Two characters, ending in the brand mark:
pithy aliasp. init, p. add auth, p. deploy. It writes a delimited block into your shell’s rc file, detected from $SHELL and the platform, and it is idempotent — a second run reports Already pithy. and changes nothing. --status reports it, --remove deletes exactly the block that was added. Either way the last line is Open a new terminal, or run: source ~/.zshrc, because an alias written into an rc file is not in the shell that wrote it.
pithy init offers it once, at the end, and only to a human at a terminal.
Tab completion is the other half. pithy completion writes its own block into the same rc file, for bash, zsh, fish and PowerShell, and covers p. as well as pithy. The script asks the installed binary on every Tab, offline, so a command that ships today completes today. pithy init asks about it right after the shortcut, under the same rules.
What output looks like
Work in progress carries a status arrow. Completion is one word. Errors lead with the problem and follow with the action.
$ pithy add auth
▸ Installing @pithy-sh/auth...
▸ Updating wrangler.jsonc...
Done.There is no emoji, no celebration, and no successfully completed in 2.3s. A genuinely long command appends the timing minimally — Done. (3.2s) — and nothing else does.
An error is two lines:
Couldn't connect to Cloudflare API.
Check your CLOUDFLARE_API_TOKEN and try again.When the failure came from a service Pithy does not control, that service’s own answer is carried on the problem line, after the words Cloudflare said: — its code, its sentence, and its documentation link, entries separated by semicolons. Pithy reports it rather than paraphrasing it, because a refusal that names only what Pithy was attempting cannot tell a missing permission from a dead credential from an outage, and each of those has a different remedy.
Cloudflare request failed: Turnstile list widgets for 'app.pithy.sh'. Cloudflare said: 10000 Authentication error — https://developers.cloudflare.com/api/resources/turnstile/subresources/widgets/methods/list
A missing grant, a dead token and the wrong account all look the same here. Check the token for Account → Turnstile, then CLOUDFLARE_API_TOKEN, then CLOUDFLARE_ACCOUNT_ID.One line, and a word rather than an indent, for a reason that is not typography. An error raised inside a Workflow step crosses a durable boundary as a single string whose newline separates the sentence from the remedy, so an indented second line was declined whole at the far end and the operator got core/workflow_failed about durable execution instead of the answer. That same newline is what the action line is, so an upstream sentence containing one would forge a remedy Pithy never wrote. A word survives a step record, a --json line and a browser alike.
The action line says which part is known and which is concluded. Cloudflare answered 10000 for one call; whether the token is missing that product’s grant, is dead everywhere, or is pointed at another account is something the operator can check and the CLI cannot, so the line orders those checks instead of asserting one. It names the permission group and not its level, because a failed read does not prove Edit was needed. When the answer does not fit, the operation label is shortened first and whole entries are dropped from the end with a trailing … — never a link cut mid-URL, and never Cloudflare’s half sacrificed to keep Pithy’s.
No stack traces reach you; a stack trace means a CLI bug rather than a project problem, and those keep theirs. Multi-row output is whitespace-aligned columns with no borders — no ASCII art, no Unicode box drawing. The whitespace is the layout.
Color is decided once, for the whole program, and respects NO_COLOR, a non-TTY stdout, and CI. Piping pithy --help into something gets you plain text, including from the parts of the help that citty renders rather than Pithy.
Prompts, and what they can answer for you
A prompt shows its default in brackets — [Y/n] means default yes, [y/N] means default no.
A prompt that can be answered from your account, is. pithy init and pithy worker add ask where a Worker will answer, per environment, and offer the account’s real Cloudflare zones rather than a free-text field. A typo fails at init with a list of what exists, instead of at deploy with a Cloudflare error to decode. Where the account cannot be reached — no credentials, a token without Zone:Read, an offline laptop, credentials for another account than the project pins — the prompt says so in one line and falls back to free text. Scaffolding has never required the network.
Every one of those is skippable, and a run that may not ask takes each one’s default. A confirmation defaults to no, so a run that cannot ask is never taken as yes: it passes --yes, or the phrase, or it is refused.
The update notifier
Pithy checks for a new CLI version in the background and never updates anything by itself.
- At most once every 24 hours, cached in the config directory’s
state.json. - Off-thread, after the command’s real work has finished. It never blocks anything.
- Written to stderr, after
Done., and only when stderr is a TTY — so it never pollutes a pipe or a CI log. - Only for a minor or major release. A patch is suppressed unless the release is flagged as a security fix, because patch noise trains people to ignore the surface entirely.
- A failed check silently keeps the cached value. An update check must never break the CLI.
Turn it off with PITHY_NO_UPDATE_NOTIFIER=1, or persistently with pithy doctor --disable-notifier. pithy doctor --enable-notifier puts it back.
The command it names is the one your installer needs, and it always resolves latest. Pithy detects which package manager installed the binary from the path it is running out of — npm, pnpm, yarn, bun, deno or Homebrew — and prints that installer’s own command. Two things about that are worth knowing, because both were bugs:
- Deno is detected by its cache, not by its install root.
deno install -g npm:@pithy-sh/cliwrites a shim, but the module deno executes lives under$DENO_DIR/npm/<registry host>/@pithy-sh/cli/<version>/. That directory is literally namednpm, so the generic npm test claims it unless the deno test runs first — and a deno user was told to runnpm i -g, installing a second copy under npm’s prefix and leaving the shim they actually invoke stale.DENO_DIRis user-settable and its platform defaults share no segment, so the mark is the layout below it: a directory namednpmwhose child is a registry hostname, matched by shape, because an adopter on a mirror caches under their own host. - The install verbs, not the update verbs.
bun update,pnpm updateandyarn global upgradeeach honor the range written into the global manifest when the binary was first installed — and for a0.xrelease a caret pins the minor, so^0.5.0can never reach0.7.1. They run, report success, and install nothing. So the notifier printsbun install -g,pnpm add -g,yarn global add, anddeno install --reload -f -g— the-ffor the same reason in a different shape, since without it deno refuses to replace an existing shim. Homebrew and npm keep their upgrade verbs, because neither records a range to respect.
Every command
| Command | What it does |
|---|---|
pithy init | Scaffold a new project and its first Worker, with a React front end when web clients call it and, if you ask, an Expo app when phones do |
pithy add | Install a capability into one Worker |
pithy remove | Unwire a capability. Manual only |
pithy setup | Make any checkout ready to develop: install, local secrets, migrate, ports, seed. Dev only |
pithy dev | Run the whole local environment under one supervisor, and read a session back |
pithy docs | Point your AI coding agent at the documentation server |
pithy migrate | Run each Worker’s migration registry against an environment, as a group |
pithy seed | Load fixtures from your own Zod schemas |
pithy provision | Create an environment’s Cloudflare resources and migrate |
pithy deploy | Ship every Worker, then prove which version answered |
pithy env | Report environments, bindings, ids and dashboard links |
pithy backup | Back up every D1 an environment’s Workers bind, FTS5 indexes included |
pithy restore | Restore a backup into an empty D1 |
pithy worker | Add, list, remove, rename and sync the Workers under apps/, and bind one to another |
pithy workflow | Start a Workflow by hand in a deployed environment, list them, and follow an instance |
pithy ui | Scaffold a React front end into a Worker, or an Expo app beside one, and wire it end to end |
pithy secrets | Create, rotate, edit, verify and provision the secret registry |
pithy cloudflare | Sign in to Cloudflare in a browser, and choose which session each directory uses |
pithy token | Mint, list, rotate, revoke and forget scoped Cloudflare API tokens |
pithy doctor | Check the toolchain, the project, and for a new version |
pithy upgrade | Reconcile package-served capabilities with their manifests |
pithy alias | Install or remove the p. shortcut |
pithy completion | Install tab completion for pithy and p., or print one shell’s script |
pithy feature | Feature environment lifecycle: create, sync, destroy, prune |
pithy dashboard | Register, rotate and revoke a management client’s access |
pithy mcp | Serve your Worker’s admin routes to an AI agent, over MCP |
pithy audit | Verify an audit export’s hash chain offline, and lock the checkpoints it is verified against |
pithy email | Provision mail, send test messages, inspect the job log |
pithy media | Provision and manage the media backends |
pithy storage | Provision and manage the R2 bucket behind storage |
pithy vector | Provision Vectorize indexes and reprocess embeddings |
pithy payments | Provision and inspect the payment rails |
pithy support | Provision and manage the support inbox |
pithy testers | Cohorts, invitations and tester rosters |
pithy turnstile | Provision the humanity check |
pithy schema | Describe every command, flag, payload and error code as JSON, from the binary installed |
pithy contract | Write each Worker’s OpenAPI document, and an AsyncAPI one beside it for a Worker that serves a socket, for a client in any language to generate from |
pithy privacy | Declare the privacy classes a project handles, close console behind them, and find the stored fields not yet marked |
Every page carries the same six sections — synopsis, flags, what it does, --json, errors, examples — so a command’s contract is specified in one place and specified completely. A test in the kit holds each page to naming every key its command’s --json payload emits, which is why the reference does not drift from the code.
The agent instructions a project carries
A project tells the agent working in it how to drive this CLI. pithy init writes a marked Pithy block into the project’s AGENTS.md, and pithy upgrade rewrites it as the CLI changes. It says five things: pithy schema --json describes every command the installed version takes; PITHY_JSON=compact keeps every --json document on one line; PITHY_NONINTERACTIVE=1 means no prompt waits; --dry-run comes before a command that changes anything; and pithy remove and every typed confirmation phrase belong to a person. Under them is the exit-code table.
The block is the only part of AGENTS.md Pithy owns. It runs between two HTML comments, so a rendered file shows neither, and a write replaces those lines and nothing either side of them. Markers Pithy cannot read unambiguously, and a symlinked AGENTS.md, are refused and reported, never guessed at.
CLAUDE.md gets one line, from pithy init alone. Claude Code reads its own file and not the shared one, so init appends Agent instructions for this project, Pithy’s included: @AGENTS.md to a CLAUDE.md the repository already has, or creates one holding just that line. A file already importing @AGENTS.md is left alone. pithy upgrade never edits CLAUDE.md.