pithy storage

Stand up what pithy add storage only wired: the per-environment R2 bucket, the storage-r2-credentials secret, and the deployed sweep worker that hosts the daily orphan reconciliation.

This is the provisioning half of the storage capability — provisioning Storage walks the same run with the account steps around it, and letting users upload files is what you build on it.

Synopsis

pithy storage provision [--worker <name>] [--r2-access-key-id <id>] [--r2-secret-access-key <key>] [--json]
pithy storage deprovision --env <environment> [--storage] [--r2-access-key-id <id>] [--r2-secret-access-key <key>] [--json]

Both subcommands reach a Cloudflare account. There is no local mode. provision has no --env flag: it spans every managed environment — staging and prod — in one run. deprovision is the opposite, and requires one: it tears down exactly the environment named.

Its Worker deploy is gated. The Worker is deployed carrying a stamp naming the package version and a hash of its resolved configuration, and a run whose stamp matches both ships nothing. Anything the gate cannot establish — no Worker, no stamp, an unreachable account — deploys. pithy deploy --env <env> ships the same Worker without provisioning anything else, and pithy deploy --env <env> --kit --force re-uploads it regardless.

Flags

provision

FlagDefaultPurpose
--worker <name>the project’s only WorkerThe app Worker whose storage(...) registration is provisioned, and whose wrangler.jsonc carries the per-environment DB binding and receives the sweep Workflow binding. Required when a project has several
--r2-access-key-id <id>R2_CREDENTIALSR2 S3 access key id the Worker presigns uploads and downloads with
--r2-secret-access-key <key>R2_CREDENTIALSThe secret half of the pair. Passing one of the two without the other is refused
--jsonfalseMachine-readable output

deprovision

FlagDefaultPurpose
--env <environment>none — requiredThe one environment to tear down, declared in pithy.config.ts. With none, or one not declared, it refuses and lists the environments it could act on
--storagefalseIrreversible. Also delete that environment’s R2 bucket and every file in it
--r2-access-key-id <id>R2_CREDENTIALSRequired with --storage: a bucket must be emptied over the S3 protocol before R2 will delete it
--r2-secret-access-key <key>R2_CREDENTIALSThe secret half of the pair
--jsonfalseMachine-readable output

What it does

The R2 key pair is supplied, not minted. Cloudflare exposes no API for creating one, so it comes from the flags or from R2_CREDENTIALS in the account config and is written into the secret as given. You make it under R2 → Manage API tokens. It is the object store’s credential, not a Cloudflare API token, so it sits outside the one-token rule.

provision runs in phases across every managed environment rather than one environment end to end, so a failure creating production’s bucket stops the run before staging’s worker is deployed against a half-provisioned account:

  1. Preflight. Verify the account can host a Workflow at all — most importantly a registered workers.dev subdomain.
  2. Buckets. Create or reuse each environment’s R2 bucket.
  3. Credentials. Write each environment’s storage-r2-credentials secret: the account id, the S3 key pair, and the bucket name the object store presigns with. No Cloudflare API token: the object store signs every call with the pair. Before the worker, because a worker that boots without its credentials fails on its first multipart abort.
  4. Workers. Deploy the prebuilt sweep worker per ready environment, wired to the provisioned bucket.
  5. Bindings. Write the sweep Workflow binding into the app worker’s wrangler.jsonc, per environment. pithy add storage cannot: wrangler requires both a name and a class_name on every workflows entry, and the deployed name is per project and environment. An entry short of either field fails the whole config, so add emits none and this run completes it.

An environment is ready when its stanza in the app worker’s wrangler.jsonc carries a DB binding with a database_id — that is, when pithy provision --env <name> has run for it. One that is not is skipped and reported, never fatal: standing staging up and proving it before production resources exist is the ordinary bring-up, and this command used to refuse it part way through, naming production, after every environment’s bucket and credentials already existed. The decision is made once, from one read, before anything is created. A declared environment with no stanza at all is a different thing and stays a refusal — that is config drift, and pithy provision --env <name> does not write a stanza.

Each environment’s deploy needs two things resolved first, and each missing one is refused rather than deployed around: the app DB id from that environment’s stanza, and the environment’s secrets database, which pithy secrets provision creates.

A Worker that owns what the host binds gets its own. When --worker names a Worker that lists a binding the storage host binds in its ownBindings, provision deploys that Worker’s own host, <project>-<env>-<worker>---storage, bound to the Worker’s own resources, and writes its Workflow bindings to reach it, <project>-<env>-<worker>---storage-<job>. The shared <project>-<env>-storage is left alone. A Worker that owns storage’s DB must own STORAGE_BUCKET too, so that host sweeps the Worker’s own bucket, <project>-<env>-<worker>---storage-bucket, against the Worker’s own rows. See a Worker’s own kit hosts.

deprovision removes one named environment’s <project>-<env>-storage-sweep Workflow and then its sweep worker, and every Worker’s own sweep host and its Workflow, found by recomputing their names. The Workflows go first, because deleting a Worker leaves the Workflows registered against it. The bucket and its files stay unless --storage is passed. With --storage, the key pair is resolved before the worker comes down: discovering it missing at the bucket step would leave the worker gone and the bucket standing.

--json

storage provision

KeyTypeMeaning
command"storage provision"The subcommand that produced this line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentsarrayOne entry per environment provisioned, in managed-environment order
environments[].envstringThe environment this entry describes
environments[].bucketNamestringThe R2 bucket objects live in for this environment
skippedEnvironmentsarrayOne entry per environment nothing was provisioned for, with its env, its reason, and the action that resolves it. For production that action says the run is a person’s decision rather than naming a fix
exitCodeintegerThe status the run exits with: 0. A run that provisions nothing writes no report

One outcome, never two. A run that went ahead writes this report alone and exits 0, whether or not some environments were skipped — exitCode says so, and it matches $?. A run in which every environment was skipped provisioned no environment, so it writes nothing on stdout: the {"error":…} line on stderr is the whole answer, exit 3, with the provisioning command as its fix.

$ pithy storage provision --worker api --json
{"command":"storage provision","schemaVersion":1,"environments":[{"env":"staging","bucketName":"acme-staging-storage"}],"skippedEnvironments":[{"env":"prod","reason":"env.prod has no DB database_id.","action":"`pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix."}],"exitCode":0}
$ echo $?
0
$ pithy storage provision --worker api --json
{"error":{"code":"core/precondition_failed","status":412,"message":"No environment is ready — staging and prod have no DB database_id.","action":"Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy storage provision --json --worker api` again.","exit":3,"retryable":false,"fix":"pithy provision --env staging --yes"}}
$ echo $?
3

The second line is on stderr, and stdout is empty.

storage deprovision

KeyTypeMeaning
command"storage deprovision"The subcommand that produced this line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
storageDeletedbooleanWhether --storage was passed, and therefore whether the buckets and their files were deleted

Errors

Each is a problem line then an action line. Under --json it is one {"error": …} line on stderr with exit, retryable and, where the cause is known, fix, and the process exits by its class.

The capability is not configured. No Worker’s pithy.config.ts composes storage. Named with --worker, it is a usage error, exit 2: another --worker is the fix. The project’s only Worker, unnamed, is core/precondition_failed, exit 3, with pithy add storage --worker <worker> --with-prerequisites as its fix, <worker> being the Worker’s apps/ directory. --with-prerequisites is there because storage declares secrets and that Worker does not compose it yet; a Worker that already does is named without it.

The capability will not load. Distinct from the above, and classified rather than assumed. The package missing answers not installed, with pithy add storage --worker <worker> --with-prerequisites — one such command for each Worker in a project with several, and in a project with no Worker, pithy worker add first. The package present with a dependency of its own not installed answers could not be loaded and tells you to install the project’s dependencies — pithy add cannot fix that one. A package that resolves and throws or will not parse answers installed and will not load, and so does one whose import names something no install provides: a # import its own imports map lacks, or a node: module this runtime does not have. A path an installed package does not have, or does not export, answers installed but incomplete. No install fixes any of those, so the action never offers one, and it names the package that wrote the import.

Credentials are missing.

No Secrets Store id. The sweep worker decrypts its credentials from it. Both subcommands resolve credentials through the same reader, so deprovision is refused without it too, though it writes no secret.

Half an R2 key pair, or none at all.

The R2 access-key pair is incomplete.
Pass both --r2-access-key-id and --r2-secret-access-key.

A malformed R2_CREDENTIALS is its own refusal — not valid JSON, or not a valid access-key/secret-key pair — rather than a SigV4 fault later.

The project has no name. Every resource name this run creates, and deprovision’s ability to find them again, derives from it.

The environment is not in wrangler.jsonc, or its DB binding has no id. When every environment is skipped, the run exits 3, core/precondition_failed, rather than reporting a success for a run that did nothing. The action names the provision each skipped environment needs, and its fix is pithy provision --env <env> --yes when exactly one of them is an environment an agent may provision; a production one is a person’s decision.

The secrets database does not exist.

The staging secrets database (acme-staging-secrets) does not exist.
`pithy secrets provision` runs against every environment, production included. That is a person's decision, not a fix. It creates this database — the sweep worker reads its credentials from it.

Examples

$ pithy storage provision
staging: bucket acme-staging-storage ready, sweep worker deployed.
prod: bucket acme-prod-storage ready, sweep worker deployed.
Done.

Take the sweep workers down and leave the files alone:

$ pithy storage deprovision --env staging
Sweep workers removed.
Done.

Take everything down, including the bytes:

pithy storage deprovision --env staging --storage --r2-access-key-id "$R2_KEY" --r2-secret-access-key "$R2_SECRET" --json
ESC