pithy add

Install a capability, wire it into one Worker’s config and bindings, and run that Worker’s dev migrations.

Synopsis

pithy add <capability> [--worker <name>] [--with-prerequisites] [--set key=value]… [--eject [--force]] [--dry-run] [--json]
pithy add mcp --floor <floor> [--worker <name>] [--with-prerequisites] [--dry-run] [--json]
pithy add --list [--json]

Flags

FlagTypeDefaultMeaning
<capability>positional—The capability name, e.g. auth. Optional only because --list runs without one
--listbooleanfalseList the capabilities you can add, with the installed ones marked. Wires nothing
--worker <name>string—Which Worker to wire it into (apps/<name>). Optional in a single-Worker project
--set key=valuestring—Override one of the capability’s config options. Repeatable
--floor <floor>string—With mcp, who may connect an agent at all: signed-in, power:<name> or entitlement:<name>. The same as --set floor=<floor>
--ejectbooleanfalseCopy the capability’s source into your repo and repoint the wiring at it
--forcebooleanfalseWith --eject, overwrite an existing local copy. Discards your edits
--with-prerequisitesbooleanfalseCompose the capabilities this one requires, if this Worker does not compose them yet
--dry-runbooleanfalseShow the plan and write nothing. Installs nothing, migrates nothing, mints nothing
--jsonbooleanfalseMachine-readable output

What it does

One capability, one Worker, in this order. Adding your first one walks the whole sequence with auth, prerequisites and all.

Install the package. The package name comes from the catalog rather than from interpolating the capability name — controlplane ships inside @pithy-sh/core and mcp inside @pithy-sh/auth, so @pithy-sh/controlplane and @pithy-sh/mcp are packages that have never existed. Your own package manager runs the install, detected from your lockfile: bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json, npm when there is none. It runs in the Worker’s own directory when that Worker is a workspace member with a package.json — every scaffolded Worker is — so the dependency is declared in apps/<worker>/package.json, sorted, and the root package.json is untouched. A Worker that is not a workspace member installs at the project root. A @pithy-sh/* package a linked checkout already provides, in the Worker’s node_modules or the root’s, is skipped, and nothing then declares it in a package.json.

A cold install can take minutes with nothing to show for it, so it is named as it starts, in the manager’s own words: ▸ Running bun add @pithy-sh/auth.... --json prints none of it.

Read the real manifest. node_modules/@pithy-sh/<pkg>/pithy.manifest.json, validated — or, for a capability that shares its package with another, its own file beside it: mcp’s is @pithy-sh/auth/pithy.mcp.manifest.json. It is found the way Node resolves it from the Worker: the Worker’s own node_modules first, then up to the project root, never above it. What the package says it needs is what gets wired — the catalog is a discovery list, not the contract.

Resolve what it composes against. A manifest’s peerCapabilities are the capabilities this one reads a seam of: auth declares secrets and email; email declares secrets; and payments, support, storage, media and turnstile all declare secrets. They are not advice. createBackend refuses to assemble a capability without them — Capability “auth” requires the “secrets” capability, which is not composed — so a Worker missing one does not start at all.

They are a graph, not a list, and they are composed deepest first: secrets before email, because email reads a secret at boot; email before auth. The order comes from walking the declarations, never from the order a manifest happens to write them in.

Each one is a real pithy add: its package installed, its config and bindings written, its dev secrets minted, its own capability/added event, sent to the same inert emitter as the add that pulled it in. Their config options take manifest defaults — you asked for one capability, not for an interview about three — and pithy add email --set … afterwards edits the same registration.

What decides whether they are composed at all is what the run can be asked:

  • A terminal. One question, for the whole cascade: auth requires secrets, email. Compose them too? A nested prerequisite is never asked about again — one intent, one question. Declining refuses the run, validation/invalid_input: somebody was asked and said no.
  • --with-prerequisites. Composes them without asking. The deterministic answer, and the one to put in a script.
  • Anything else — --json, --no-input, PITHY_NONINTERACTIVE=1, no TTY, an agent — is refused input/required with "flag": "--with-prerequisites", exit 2, naming the exact commands in the order they must run. Nothing is wired: an install has happened, because that is how the manifest was readable, and the config is untouched.

Composing something nobody asked for is not a thing to do behind an adopter’s back. Reporting Done. on a project that cannot boot is worse. A prompt where there is someone to ask, and a flag where there is not.

Wire that Worker. apps/<name>/pithy.config.ts gains the import and the registration call. apps/<name>/wrangler.jsonc gains the manifest’s required bindings, in every environment stanza the file declares, plus any Durable Object class migrations. And the module that Worker’s main names gains an export { <Class> } from "…"; for every Durable Object class it now binds.

Handler source stays in the package. Only the thin registration lands in your repo.

Every binding whose entry add can complete offline is written: d1_databases, kv_namespaces, r2_buckets, ai, durable_objects, ratelimits, workflows, a queue’s queues.producers entry naming the queue pithy provision creates and, for a queue the capability consumes, its queues.consumers entry, send_email, artifacts, and the account-level kinds you stand up yourself — hyperdrive, browser, images, analytics_engine_datasets, pipelines, mtls_certificates and dispatch_namespaces, each pointed at the binding’s target. A few are worth a sentence each.

A rate limiter is a policy, not a resource — nothing exists behind it in your account. It is written at 100 requests per 60 seconds, per client IP, which is a flood guard rather than a product rule. Tune it in wrangler.jsonc; add never rewrites an entry you have changed. A re-run over a Worker that already has every binding leaves wrangler.jsonc byte-identical, and a run that does add one keeps the file’s comments, indentation, object layout and trailing commas; an array is laid out the way Biome prints it. Cloudflare accepts a period of 10 or 60 and nothing else.

A Durable Object is two halves, and only one of them is config. The durable_objects.bindings entry names a class_name, and wrangler resolves that name against the module main names — a Worker whose entry does not export the class is refused at deploy with Your Worker depends on the following Durable Objects, which are not exported in your entrypoint file. So add writes the export too, under a comment saying what the block is. Delete a line from it and the Worker stops deploying; pithy remove takes it back out. A class the entry already exports, however you wrote it, is left alone.

A Workflow entry names the capability’s host Worker across scripts — <project>-<env>-<capability>-<job> running in <project>-<env>-<capability> — so it is complete before that host exists, and wrangler dev binds it either way. A Worker that owns a binding the host binds names its own host instead, <project>-<env>-<worker>---<capability>-<job> running in <project>-<env>-<worker>---<capability> (a Worker’s own kit hosts). The host itself is deployed by pithy <capability> provision, which notes says.

A D1 entry names the database pithy provision creates, <project>-<env>-<binding>, and a binding the Worker lists in ownBindings gets the Worker’s own name instead (shared by default, owned when a Worker says so). An owned entry in the top-level stanza also carries a database_id of its own, so local dev keeps it apart from the shared database.

A queue producer names the queue pithy provision creates, under the same rule as every other resource, <project>-<env>-<binding>, so the entry is complete before the queue exists. A queue the capability also consumes gets a queues.consumers entry beside its producer, carrying the capability’s max_retries, max_batch_size and dead_letter_queue, the dead-letter queue named by the same rule. A consuming queue counts as bound only when both entries are there: a producer with no consumer is a queue that fills and is never read, so pithy upgrade reports it missing and writes the consumer.

An artifacts entry names this environment’s namespace of repositories, <project>-<env>, so it is complete before any repository exists. There is nothing to create: Cloudflare makes the namespace on its first repository. With no project name resolved there is no namespace to name, and the entry is skipped with the reason rather than half-written.

What is left out is left out because wrangler would refuse the file: a vectorize entry needs the index_name provisioning mints, and a secret has no array in wrangler.jsonc at all. Those come back in notes.

Write the Workers test bindings. The project-root vitest.workers.config.ts runs every Worker’s *.workers.test.ts, and the first request through a Worker’s fetch checks every binding its composition requires. So add also writes the test bindings the capability’s manifest declares into that file’s miniflare options: a D1 database, KV namespace or R2 bucket by name, a rate limiter at its declared limit, and a value as a call into the capability’s own test utilities. pithy add secrets writes SECRETS into d1Databases and SECRETS_ENCRYPTION_KEYS: devEncryptionKeys() into bindings, imported from @pithy-sh/secrets/src/test-utils/devEncryptionKeys. The same bindings go on the target Worker’s Cloudflare.Env in src/cloudflare-test.d.ts, SECRETS: D1Database; and SECRETS_ENCRYPTION_KEYS: string;, so a test reading env.SECRETS typechecks. A binding already there is left as you wrote it, and a re-run writes nothing.

A rate limiter carries its namespace_id. Miniflare refuses a limiter without one, so the test entry gets the id the kit derives from the binding name, the same one add writes into a new wrangler.jsonc entry for it: AUTH_RATE_LIMITER: { namespace_id: "3093", simple: { limit: 100, period: 60 } }. That is the one repair a re-run makes to a binding already there: a limiter stated without a namespace_id gets that id, and nothing else in its entry or the file changes. The id names a test-only counter with no live budget behind it, so filling it in is safe here; the namespace_id in wrangler.jsonc is never rewritten. --dry-run shows the line.

A binding no project-wide test config can provide on its own is named in notes instead, on every run. That covers a Durable Object or a Workflow, whose class lives in the Worker’s entry, and a remote binding such as Vectorize, Workers AI or Artifacts: email: vitest.workers.config.ts cannot bind EMAIL_SENDER. A Workers test that sends a request through the Worker's fetch answers 500 without it. A config with no miniflare block gets a note naming the bindings to add by hand. A project with no vitest.workers.config.ts gets no config edit, and a Worker with no src/cloudflare-test.d.ts gets no declaration. A binding the manifest marks optional is written only when the Worker’s config makes the capability require it, as controlplane({ replayBackend: "kv" }) requires CONTROL_PLANE, so run add again after changing such an option. pithy doctor names a composed capability whose test bindings are missing or incomplete, and pithy remove takes them out again.

A package that config imports is declared at the root too. vitest.workers.config.ts loads from the project root, and under a package manager that does not hoist, such as Bun’s isolated linker or pnpm, the root resolves only what its own package.json declares. So a package a test binding’s value imports that the root does not declare becomes a root devDependency, sorted, at the range a workspace member declares it at, and add runs <pm> install at the root to bring the lockfile in step. pithy add secrets declares @pithy-sh/secrets there for devEncryptionKeys. The Worker keeps its runtime dependency. A package no member declares has no range to write, and is left for pithy doctor to name.

Scaffold the config options. Values come from --set first, then from a prompt when a human is attached. An option whose default is an object or an array is left as the manifest scaffolds it — a secrets registry is not something anyone types at a prompt.

An option with no default is required. That is the whole declaration: a capability that states a default has an answer the kit is willing to pick, and one that states none has an answer only you can give. A prompt asks it with nothing to accept by pressing enter, and a run with no human is refused input/required unless it carries --set key=value — "flag": "--set", with every key=value the first unanswered option takes in choices. payments.billingSubject is the first — whether an entitlement is held by a person or a company, which lands in a column and a UNIQUE index — and nothing guesses it. An option that also states its choices is asked as a list, and --set refuses anything outside them.

pithy add mcp takes a floor. mcp lets your users’ agents use the app as them, and composing it means choosing who may connect one at all. There is no default. --floor signed-in admits every signed-in user, --floor power:<name> only a caller whose role holds that power, and --floor entitlement:<name> only a caller holding that entitlement; they are written as floor: "signed-in", floor: { power: "<name>" } and floor: { entitlement: "<name>" }. mcp requires auth, so a Worker that does not compose it is refused naming pithy add auth, as any prerequisite is. Its database is the one auth’s registration names, DB when it names none, because the provider’s tables live beside auth’s. A config that already composes an OAuth provider into auth is refused, naming oauthProvider() to remove: mcp composes the one its endpoint uses. Its notes name what follows — pithy ui add for the consent and connected-applications screens, and describeRoute({ operation, tool }) to make a route a tool.

A choice whose other half is code

Some values compose only alongside a function. pithy add renders JSON into pithy.config.ts, not behavior. Where the kit knows what that function’s file looks like, it writes one: the choice is taken, a seam module is scaffolded beside it, and the Worker refuses to boot until you have finished the module.

$ pithy add payments --worker api --set billingSubject=organization
Wired payments into api.
app: 1 applied.
apps/api/src/billing/subject.ts is scaffolded, not written. This Worker refuses to boot until resolveSubject answers which organization a caller is acting for.
Done.

pithy.config.ts gets billingSubject: "organization", an import of resolveSubject, and that name passed to payments(...). apps/api/src/billing/subject.ts exports a resolver marked unimplemented.

The rule underneath it: the scaffold is a marked absence, never a working stub. A resolveSubject returning nothing would compose cleanly and then deny every entitlement gate — indistinguishable from a customer who has not paid, with a support ticket from a paying company as the first symptom. So the scaffolded resolver answers nothing at all and says so, and @pithy-sh/payments refuses the Worker’s entrypoint while it is still in place. Your pithy.config.ts keeps loading, so every other pithy command in the project keeps working while you write it.

Re-running is safe. pithy add payments --set billingSubject=organization a second time writes nothing: the registration is already there, and a file at the seam’s path is yours whatever it contains.

A --set on a choice the CLI can neither write nor scaffold is refused at the flag, naming what to do instead, rather than writing a config the kit will then refuse to load. No capability ships one today.

Eject, if asked. Before the migrations, because eject repoints the config import at the local copy and promotes the capability’s runtime dependencies into the Worker — an install run where the package’s own install ran, so they land in apps/<worker>/package.json — and the migrate step has to load the config with everything it imports present. That install is named as it starts, the same way.

Run that Worker’s dev migrations. The config is re-read after wiring, so the migration that just arrived is in the registry. Local Miniflare state lives at the project root, shared with wrangler dev. Each database and migration is named as it starts, as pithy migrate names them. --json prints none of it.

Bootstrap what is left. Dev-only values a capability needs to boot — the master key pithy add secrets mints, the session secret auth needs — land in <config>/<project>/secrets.jsonc, outside every checkout. What only a provision command can supply comes back as a note instead.

pithy add audit offers a privacy declaration, once, at a terminal. Declare the privacy classes this project handles too? — asked only when the root pithy.config.ts declares none, and defaulting to no. Yes runs pithy privacy enable, which asks which classes. No leaves the project as it was. An audit trail records who touched what, and a declaration says what there is to touch, so each command offers the other. --json and a run that cannot ask are never offered anything.

add runs against no Cloudflare account. It writes config and local D1 only. Bindings whose resources live in the account are named in notes rather than created here. It emits capability/added at info severity, on success and on failure alike, but against dev, whose emitter is inert: an add changes nothing shared, so nothing is recorded, and no Cloudflare credentials are read for it. A shell exporting another account’s credentials therefore does not refuse an add.

The project needs a name. It leads every resource name add proposes, and it claims the database the closing dev migration writes to. A project without one is told to set it before anything is installed, rather than left half-configured around an unowned database.

Which Worker. --worker names it. A single-Worker project needs no ceremony. A project with several never guesses: it prompts a human, and anyone else gets input/required, naming --worker and every Worker in choices.

Idempotent. A second pithy add auth wires nothing new, and says auth is already wired into <worker>. Its install still runs, so a release of the package newer than the one installed moves the declaration and the lockfile to it. Adding the same capability to a second Worker runs that Worker’s own install, declaring the package in its own package.json, and writes its config and bindings.

Seeing it first: --dry-run

--dry-run is the add, made in a copy. The whole flow above runs — the same prerequisite refusal, the same required options, the same config, binding, entry, seam, test-binding and manifest writes — against a private copy of the project under the system temporary directory, and the plan is what changed there: each file with its diff, so the bytes you review are the bytes the add writes. The copy is gone before the command exits. The install, the dev migrations and the dev secrets are named in the plan rather than run. The install declares the package at ^<installed> in the package.json it would run against — the Worker’s own for a workspace member, the root’s otherwise — and is named on that file, with the declaration as the diff, when that changes the declaration. A package already declared at that range is no edit, but the real install still runs and names no version, so a release newer than the installed one moves the declaration and the lockfile to it. A dry run reads no registry, so it names that install as a step, with the condition under which it changes the two files. With --eject, the dependency install is named only when it would change a declaration. When a test binding’s import is declared at the root, the root install that follows is named on the root package.json the same way. The manifest has to be installed, because it is what says what a capability wires, so a capability that is not installed is refused, exit 3, naming the install command. For a Worker that is a workspace member that command starts cd apps/<worker> &&, since that is where the real add installs; run at the root, it would declare the package there instead.

$ pithy add audit --dry-run
Would wire audit into board.
Would edit apps/board/package.json.
  Runs bun add @pithy-sh/audit here, which also writes the lockfile.
Would edit apps/board/pithy.config.ts.
Would edit apps/board/wrangler.jsonc.
Then applies board's pending dev migrations to the local database.
Delivers the project's dev secrets to each Worker's .dev.vars and to the local SECRETS store.
Dry run. Nothing written.

A plan names only the files the add would change. A step that would leave a file as it is plans no edit, so the dry run and the real run agree file by file. On a Worker whose pithy.config.ts already registers the capability, both say <capability> is already wired into <worker>. in place of Would wire … and Wired …, and the plan lists only what would still change: a binding the config has since lost, or a declaration at another range. The install that still runs is named under it as a step.

$ pithy add audit --dry-run
audit is already wired into board.
Runs bun add @pithy-sh/audit for apps/board/package.json. It leaves that file and the lockfile as they are while 0.4.0 is the newest release of @pithy-sh/audit, and moves both to a newer one if it is out.
Then applies board's pending dev migrations to the local database.
Delivers the project's dev secrets to each Worker's .dev.vars and to the local SECRETS store.
Dry run. Nothing written.

--json

One line, one object. Two shapes: one for --list, one for a real add. A failure is one {"error": …} line on stderr, with exit, retryable and, where the cause is known, fix, and the process exits by its class.

pithy add --list --json

$ pithy add --list --json
{"command":"add","schemaVersion":2,"capabilities":[{"name":"auth","package":"@pithy-sh/auth","requires":["secrets","email"],"whenToEnable":"Authentication and session management.","installed":false},{"name":"mcp","package":"@pithy-sh/auth","requires":["auth"],"whenToEnable":"Let your users' agents use your app as them. …","installed":false}, …],"manifestFaults":[]}
KeyTypeMeaning
command"add"The command that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
capabilitiesarrayThe built-in catalog, in catalog order, each entry tagged with whether this project has it installed
capabilities[].namestringThe capability name — the pithy add <name> argument
capabilities[].packagestringThe npm package it ships in. @pithy-sh/<name> for all but controlplane, which ships inside @pithy-sh/core, and mcp, which ships inside @pithy-sh/auth
capabilities[].requiresstring[]The capabilities it requires, which --with-prerequisites composes first. Empty when it requires none
capabilities[].whenToEnablestringOne-line rationale: why a project would enable this
capabilities[].installedbooleanWhether a node_modules/@pithy-sh in this project — the root’s or any workspace member’s — holds a usable manifest for it
manifestFaultsarrayInstalled packages shipping a manifest that is present and unusable. Empty on a healthy install
manifestFaults[].packagestringThe package the manifest was read from, as you would name it: @pithy-sh/audit
manifestFaults[].filestringThe manifest file within that package: pithy.manifest.json, or a companion such as pithy.mcp.manifest.json
manifestFaults[].reasonstringWhy it could not be used — the schema’s refusal text, or the errno where the file would not open

A faulted package is reported rather than refused: one broken manifest must not cost you the other fifteen entries. In human output the faults go to stderr; the listing still goes to stdout.

pithy add <capability> --json

$ pithy add secrets --json
{"command":"add","schemaVersion":2,"capability":"secrets","worker":"board","deployedAs":"replay-board","package":"@pithy-sh/secrets","packageManager":"npm","alreadyWired":false,"databases":[{"database":"app","binding":"DB","results":[{"migrationName":"0300_auth_0001_init","direction":"Up","status":"Success"}]}],"kvNamespaces":[],"notes":["SECRETS_STORE_ID is not recorded, …"]}
KeyTypeMeaning
command"add"The command that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
capabilitystringThe capability’s name, taken from the manifest rather than from the argument
workerstringThe apps/ directory that was wired. What --worker accepts, and what every path in this payload is relative to
deployedAsstringThe same Worker’s deployed script name, from wrangler.jsonc. What the Cloudflare dashboard shows
packagestringThe npm package the capability ships in
packageManager"npm", "pnpm", "yarn" or "bun"Your package manager, detected from the lockfile. Reported whether or not an install ran — it is a fact about the project, not a record of a spawn
alreadyWiredbooleanWhether the Worker’s pithy.config.ts registered the capability before this add. When true nothing new is wired, and under --dry-run plan.files lists only what would still change — empty when nothing would
databasesarrayThe dev migration run, one entry per database this Worker’s registry touched
databases[].databasestringThe database name — a capability’s databases key
databases[].bindingstringThe D1 binding it resolves to in this Worker’s wrangler.jsonc
databases[].resultsarrayThe migrations this Worker’s capabilities contributed, and how each fared. Empty under --dry-run, which runs none
databases[].results[].migrationNamestringThe migration’s namespaced name, e.g. 0300_auth_0001_init
databases[].results[].direction"Up" or "Down"The direction it was executed in
databases[].results[].status"Success", "Error" or "NotExecuted"NotExecuted means an earlier migration failed first
databases[].sharedWithstring[]The other Workers bound to this same physical D1. Present only when a database is shared
kvNamespacesarrayKV namespace titles to create, one per environment that gained the binding. Reported rather than written, because a kv_namespaces entry has no title field — the name can only land in the account. D1’s name goes into wrangler.jsonc as database_name
kvNamespaces[].bindingstringThe Worker env binding the name is proposed for, e.g. SESSIONS
kvNamespaces[].envstringThe environment whose stanza declares it — dev for the top-level one
kvNamespaces[].namestringThe proposed resource name, <project>-<env>-<binding>, or the Worker’s own for a binding it lists in ownBindings
notesstring[]What add finished off-config, what only a provision command can supply, and each test binding vitest.workers.config.ts cannot hold. One line each, in order — a prerequisite’s notes come first, so the dev master key pithy add secrets mints is never swallowed. A line starting <capability>: vitest.workers.config.ts cannot bind asks for no command: it names a Durable Object, Workflow or remote binding that a Workers test through that Worker’s fetch lacks. Empty for a capability every one of whose bindings add writes into both wrangler.jsonc and the Workers test config
prerequisitesstring[]The capabilities composed on the way to this one, deepest first. Empty when it declares none, and empty on a re-run into a Worker that already composes them
dryRunbooleanWhether this was --dry-run. Nothing was written when it is true, and every other key is what the add would report
planobjectPresent only under --dry-run: what the add would write. files carries each file’s diff; secrets the dev secrets it would mint; notes the migrate it would run
nextobject[]The step this add left required, in order, and absent otherwise — never empty. pithy provision --env <env> --yes for a declared environment a provision had readied that gained a binding without an id; else pithy migrate --env <env> when a provisioned environment has migrations this add applied only in dev
ejectobjectPresent only when --eject ran
eject.capabilitystringThe capability that was forked
eject.pathstringThe Worker-relative directory the source was copied into, capabilities/<cap>
eject.promotedDependenciesstring[]The name@version dependencies promoted into the Worker’s own package.json (the root’s, for a Worker that is not a workspace member). Workspace-internal ones are excluded
eject.forcedbooleanWhether an existing local copy was overwritten (--force)

kvNamespaces is empty when the capability needs no KV, when no project name was resolved, and on a re-run — a binding already present is left alone.

Errors

No capability named.

$ pithy add
Name a capability to add.
Run pithy add --list to see what's available.

Several Workers, none named. The prompt is attached only when a human is, so this is what an agent gets.

$ pithy add audit --json
{"error":{"code":"input/required","status":400,"flag":"--worker","choices":["deck","tally"],"message":"This project has several workers, so which one to wire is ambiguous.","action":"Pass --worker <name>. Known: deck, tally.","exit":2,"retryable":false}}

The choices are the Workers’ apps/ directories, which is what --worker takes — never their deployed names.

A --worker that names nothing.

$ pithy add audit --worker nope
No worker named "nope".
Run pithy worker list to see this project's workers. Known: deck, tally.

An unknown --set key. The valid keys come back with it, so an agent and a human get the same correction.

$ pithy add auth --set nope=1
auth has no config option "nope".
Valid keys: basePath, baseURL, disableSignUp.

A --set with no =.

$ pithy add auth --set nope
--set expects key=value, got "nope".
Pass --set key=value.

A --set on an option only you can write. An option whose default is an object or an array takes more than a string.

$ pithy add secrets --set registry=x
secrets option "registry" is not settable from the command line.
Edit registry in the worker's pithy.config.ts — pithy add scaffolds it empty.

A required option nobody answered, in a run that cannot be asked. The action names the flag and every value it takes.

$ pithy add payments --json
{"error":{"code":"input/required","status":400,"flag":"--set","choices":["billingSubject=user","billingSubject=organization"],"message":"payments needs a value for billingSubject, and nothing in this run names one.","action":"Pass --set billingSubject=user or --set billingSubject=organization.","exit":2,"retryable":false}}

pithy add mcp with no floor, in a run that cannot be asked. Exit 2, and the action says what each floor admits.

$ pithy add mcp --json
{"error":{"code":"input/required","status":400,"flag":"--floor","choices":["signed-in","power:<name>","entitlement:<name>"],"message":"mcp needs a value for floor, and nothing in this run names one.","action":"Pass --floor signed-in, --floor power:<name> or --floor entitlement:<name>. signed-in: Every signed-in user may connect an agent. power:<name>: Only a caller whose role holds that power. entitlement:<name>: Only a caller holding that entitlement.","exit":2,"retryable":false}}

pithy add mcp beside an OAuth provider.

$ pithy add mcp --floor signed-in
auth({ plugins }) already composes an OAuth provider.
Remove oauthProvider() from auth({ plugins: [...] }) and its import, then run `pithy add mcp --worker board --set floor=signed-in` again. mcp composes the one its endpoint uses.

A --set outside an option’s choices.

$ pithy add payments --set billingSubject=team
payments option "billingSubject" does not take "team".
Pass one of: user, organization.

A prerequisite this Worker does not compose, in a run that cannot be asked. The commands come back in dependency order.

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

Every command it names runs as written: it names the Worker by its apps/ directory and keeps the flags this run was given, --json included.

A capability whose manifest is not there, when the install did not run or did not land. No capability named "<name>" is installed., with Run `pithy add <name> --worker <dir> --with-prerequisites` to install it. — naming the Worker by its apps/ directory, and --with-prerequisites when the capability brings any that Worker lacks. In a project with several Workers it names one such command per Worker, joined by “or”.

A malformed manifest on the direct path. The --list scan reports a fault and carries on; asking for that capability by name refuses, naming the package and the schema’s own reason.

--eject over an existing fork.

$ pithy add audit --eject
capabilities/audit already exists.
Edit the local copy, or re-run with --force to overwrite it (discards your changes).

A project with no name. Thrown before the package is installed, so a nameless project is told to set one rather than left half-configured around an unowned database.

Examples

Wire a capability into a single-Worker project.

$ pithy add audit
Wired audit into board.
app: 1 applied.
Done.

Compose a capability and everything it requires, in one command.

$ pithy add auth --with-prerequisites
Composed secrets, email into board first — auth requires them.
Wired auth into board.
app: 1 applied.
Minted a dev master key as SECRETS_ENCRYPTION_KEYS, into ~/.config/pithy/replay/secrets.jsonc. Local only, and it reaches each Worker's generated .dev.vars.
Minted a dev email-link-signing-key into ~/.config/pithy/replay/secrets.jsonc. Local only.
Minted a dev auth-session-secret into ~/.config/pithy/replay/secrets.jsonc. Local only.
Deployed environments need pithy secrets create auth-session-secret.
Done.

Let your users’ agents in, for callers whose role holds agents:use.

$ pithy add mcp --floor power:agents:use
Wired mcp into board.
app: 1 applied.
Run pithy ui add for the agent-consent and connected-applications screens. An agent's user signs in and approves on the first, and revokes on the second.
A route is a tool only when it says so: describeRoute({ operation, tool: true }) on a GET, describeRoute({ operation, tool: { effect } }) on anything else, with the effect writes, sends, charges or deletes.
Done.

Name the Worker in a project with several, and set config options without a prompt.

pithy add audit --worker deck
pithy add auth --set basePath=/session --set disableSignUp=true

Fork the source and own it.

$ pithy add audit --eject
Wired audit into board.
Ejected audit into apps/board/capabilities/audit/. It's yours now — @pithy-sh/audit no longer upgrades it.
Promoted 4 dependencies. @pithy-sh/audit is safe to remove.
Done.

An ejected capability is never reconciled again — pithy upgrade reports it as skipped. See Eject a capability.

See what there is.

$ pithy add --list
auth          Authentication and session management.
secrets       Encrypted secret storage with a worker-only master key and automatic at-rest key rotation.
…
ESC