pithy media

Stand up what pithy add media only wired: the per-environment R2 bucket, the two credential secrets, the two signing keys private media is delivered through, and the deployed media worker that hosts the enrichment Workflows.

Synopsis

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

This is the provisioning half of the media capability, and provisioning Media walks the same run with the account steps around it.

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 media(...) registration is provisioned, and whose wrangler.jsonc carries the per-environment DB 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. Made under R2 → Manage API tokens
--r2-secret-access-key <key>R2_CREDENTIALSThe secret half of the pair. Passing one 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 with every object 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

No Images or Stream token is asked for. Media mints uploads, changes signing and reads what was served with the application’s one runtime token, which pithy secrets provision mints per environment (Cloudflare API tokens). The run refuses before it writes anything while any environment’s Secrets Store holds no runtime token, and names pithy token mint runtime --env <env>: a bundle rewritten first would break a Worker still on the old kit. A project storing both types in R2 calls Cloudflare for nothing, so its media host binds no runtime token and the run asks for none.

The R2 pair is supplied, not minted. Cloudflare exposes no API for creating an R2 S3 access-key pair. It comes from the flags or from R2_CREDENTIALS in the account config, and is written into the secret as given. It is the object store’s credential, outside the one-token rule. No Cloudflare API token is stored beside it: the object store signs every call with the pair.

provision runs in phases across every managed environment rather than one environment end to end, so a failure in production stops the run before staging 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. Then, while images live in Cloudflare Images and visibility.allowed admits anything but public, refuse if any Images variant is set to neverRequireSignedURLs, naming each: such a variant serves a private image to anyone holding its URL. Nothing has been created yet.
  2. Resources. Create or reuse each environment’s R2 bucket. Records live in D1, so no KV namespace is created.
  3. Credentials. Write each environment’s two secrets. Two, because there are two owners: media-storage-credentials is media’s account id and nothing else, and media-r2-credentials belongs to pithy storage’s ObjectStore, which media presigns through and whose key pair media never sees.
  4. Signing keys. Where some record could be private, write media-images-signing-key — the account’s Images URL-signing key, read as found, or created as pithy when the account has none — and media-stream-signing-key, a Stream signing key. Cloudflare hands a Stream key’s private half back once, at creation, so one is created only when the environment holds none; a re-run keeps the stored key. A non-public Images or Stream asset is uploaded with requireSignedURLs, and the Worker signs a short-lived URL with these for a caller who may read it.
  5. Workers. Deploy the prebuilt media worker per ready environment, wired to the resources the secrets already name.

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.

The environment’s secrets database, which pithy secrets provision creates, is still resolved first and still refused when missing.

A Worker that owns what the host binds gets its own. When --worker names a Worker that lists a binding the media host binds in its ownBindings, provision deploys that Worker’s own host, <project>-<env>-<worker>---media, bound to the Worker’s own resources, and writes its Workflow bindings to reach it, <project>-<env>-<worker>---media-<job>. The shared <project>-<env>-media is left alone. An owner of MEDIA_BUCKET has its own bucket, <project>-<env>-<worker>---media-bucket, which that host binds. See a Worker’s own kit hosts.

deprovision removes one named environment’s media worker and its four enrichment Workflows (<project>-<env>-media-image-to-text, -audio-transcribe, -video-transcribe and -doc-extract), and every Worker’s own media host and its Workflows, found by recomputing their names. The Workflows go first, because deleting a Worker leaves the Workflows registered against it. Its bucket and its objects 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

media provision

KeyTypeMeaning
command"media provision"The subcommand that produced this line
schemaVersionintegerThe version of this payload’s shape, 2. 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 media 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 media provision --worker api --json
{"command":"media provision","schemaVersion":2,"environments":[{"env":"staging","bucketName":"acme-staging-media"}],"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 media 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 media 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.

media deprovision

KeyTypeMeaning
command"media 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 that environment’s bucket and its objects 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 media. 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 media --worker <worker> --with-prerequisites as its fix, <worker> being the Worker’s apps/ directory. --with-prerequisites is there because media 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 media --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. 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 media worker decrypts its credentials from it.

Half an R2 key pair, or none at all.

An Images variant serves unsigned. While some record could be private, a variant set to neverRequireSignedURLs would deliver it to anyone. Refused at preflight, before anything is created.

Cloudflare Images variant `thumb` serves every image unsigned, so a private image would be public through it.
Turn off neverRequireSignedURLs on each in Images → Variants, or narrow visibility.allowed to ["public"] in media({ … }), then re-run.

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 no environment is ready at all, it is core/precondition_failed, exit 3. 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. pithy secrets provision creates it, and runs against every environment, production included — so the refusal names it as a person’s decision and carries no fix.

Examples

$ pithy media provision
  staging  bucket acme-staging-media ready, worker deployed
  prod     bucket acme-prod-media ready, worker deployed
Done.
$ pithy media deprovision --env staging
staging: media worker removed.
Done.
pithy media deprovision --env staging --storage --json
ESC