Blog

How far you get before you need a Cloudflare account

2026-10-24

An isometric illustration of an engine block on a wheeled test stand on a raised isometric platform, with smaller related objects on tiles around it

On 2026-09-05 we read our own Cloudflare account through its API and wrote the numbers down. D1 databases: zero. Workers scripts: zero. KV namespaces: zero. R2 buckets: zero. Workflows: zero. Nothing had ever been provisioned — not a partial state, not a stale one. Empty.

That same day, the application that account would eventually host was running on a laptop. Signed in. Passwordless auth, a payments integration, an audit trail, outbound mail, a seeded database with a cast of people in it, and a front end serving every screen.

That gap is the point of this post. You can build nearly all of a product before you owe anybody money, and you should — the parts that only come up once an account, a domain and a pipeline are involved are a short list, and you want to meet them on their own.

463 of this product’s 572 commits landed before that account held a single resource — 81%. A commit count is a crude measure of work and the remaining 19% took three weeks, so read it as a shape rather than a ruler. The shape is right.

flowchart TD
  subgraph local["On your machine. No Cloudflare account."]
    A["pithy init"] --> B["pithy ui add react"]
    B --> C["pithy add secrets, email, audit, auth, payments"]
    C --> D["pithy migrate"]
    D --> E["pithy seed"]
    E --> F["pithy dev"]
  end
  subgraph cloud["Needs a Cloudflare account and a domain."]
    G["pithy secrets provision"] --> H["pithy provision --env staging"]
    H --> I["pithy email provision"]
    I --> J["pithy deploy --env staging"]
    J --> K["pithy deploy --env prod"]
  end
  F -->|"81% of this product's commits landed above this line"| G

What does the local loop give you?

Eleven commands take an empty repository to a running application:

pithy init --name dash --worker board
bun install
pithy ui add react --worker board
pithy add secrets   --worker board
pithy add email     --worker board
pithy add audit     --worker board
pithy add auth      --worker board
pithy add payments  --worker board
pithy migrate
pithy seed
pithy dev

A capability is the unit pithy add installs: a package bringing its own tables, routes, config schema and bindings, composed into your Worker rather than sitting beside it. This application composes nine.

None of those commands reaches a network except to install packages. pithy seed loads your fixtures and mints a dev session, so the app comes up signed in rather than round-tripping a sign-in link on every restart. Press l and your browser opens at the dev-login route, already authenticated. The seeded cast here is 29 people across four fictional organizations — enough to catch the bugs that only appear once a list has more than one row.

pithy dev starts more than your Worker. A capability that owns Workflows ships a host Worker of its own, and the supervisor runs those too, wiring them to each other over localhost:

flowchart LR
  subgraph supervisor["pithy dev — one supervisor, one Ctrl-C"]
    APP["your Worker<br/>localhost:8787"]
    EM["email host<br/>localhost:8788"]
    SE["secrets host"]
  end
  APP -->|"EMAIL_SENDER · Workflow · local"| EM
  APP -->|"SECRETS_ORIGIN"| SE
  APP --> DB[("DB · SECRETS · EMAIL_SUPPRESSIONS<br/>D1, under Miniflare")]
  KEYS["secrets.jsonc<br/>outside every checkout"] -.->|"regenerates .dev.vars each run"| APP

The storage is real, not mocked. D1 and KV run under Miniflare, Cloudflare’s local simulator for the Workers runtime. Your SQL is SQL, your KV semantics are KV semantics, and nothing is a stub you delete later.

None of that depends on our machine being well-worn. We scaffolded a fresh project on the current release into an empty directory, with an isolated home directory and no Cloudflare credentials. Part of what pithy dev bound:

env.EMAIL_SENDER (EmailSendWorkflow (defined in probe-dev-email))   Workflow        local
env.SECRETS (probe-dev-secrets)                                    D1 Database     local
env.DB (probe-dev-db)                                              D1 Database     local
env.EMAIL_SUPPRESSIONS (probe-global-email-suppressions)           D1 Database     local
env.AUTH_RATE_LIMITER (100 requests/60s)                           Rate Limit      local

Every one of them local — including the Workflow binding, which used to be the first thing that sent you off to get an account.

Where do your secrets live while you do this?

Not in your checkout. They live in one file outside every checkout, and each Worker’s .dev.vars is generated from it on every run. The reason is sharper than tidiness: an API token is the credential every other credential is minted from, and npm pack does not consult your .gitignore when your package.json sets files, so a token in a file inside a repository can reach a published tarball. Gitignoring it was never the protection it looked like. Keeping it out of the tree is.

What does the kit refuse to guess?

Two things, and the line between them is the decision worth stealing.

Where the missing piece is data, it scaffolds a working example — a secret registry, a ledger’s currencies — with a comment telling you to replace it, so your project compiles and boots before you have written a line of your own.

Where the missing piece is behavior, it refuses at the flag. A stub would be worse: a resolver that returns nothing loads cleanly and then denies every request downstream, and a Worker whose first symptom is a support ticket from a paying customer is worse than one that will not boot.

Prerequisites work the same way, and the refusal names both routes out rather than leaving you to work out which command caused a failure three steps later:

$ pithy add email --worker board
email requires secrets, which board does not compose.
Run pithy add email --with-prerequisites, or compose it first: pithy add secrets.

Does the test suite need an account?

No, and it is enforced rather than hoped for. A checkout with no credentials runs the suite and gets green. The tests needing a real third-party object sit in a separate tier the default config excludes, and that tier reports every fixture as absent, declined or malformed before collecting a suite. A skipped suite is not a passing one.

When do you actually have to pay?

Later than you would expect. The local loop above needs no Cloudflare account at all, and once you deploy, a free account carries most of what the kit composes: Workers, D1, KV, and even Workflows — the free plan runs those, with real limits on compute time per step and concurrent instances rather than a wall.

The clear exception is outbound mail. Sending to arbitrary recipients needs Workers Paid, which has a minimum charge of $5 a month. Inbound Email Routing is free on any plan, and so is sending to an address you have already verified in Email Routing — which is enough to exercise the whole sign-in flow against yourself before you pay for anything.

So: free to build, free to deploy a good deal of it, and five dollars at the point where you need to send mail to somebody who is not you.

So what does the last 19% cost?

Mostly setup rather than breakage, and the setup is shorter than you would guess.

Here is the whole of the problem. Your laptop reads its credentials from your home directory, and a CI runner has no home directory. Everything the local loop picked up for free has to be handed over explicitly, once.

Mint a scoped credential rather than reusing your own. pithy token mints an account token scoped to one profile — ci-system is the CI one — so what your pipeline holds can deploy and migrate and nothing else:

pithy token mint ci-system --env staging --json

No subcommand ever prints a token value. Not on stdout, not in --json, not in an error. The value goes to a 0600 handoff file keyed by environment, and pithy doctor prints the path on every run.

Then let gh place it. This is where the two tools meet: pithy mints the credential, the GitHub CLI creates the environment and sets what it holds, and the whole setup becomes a script instead of a tour of two web consoles.

REPO=your-org/your-repo
TOKENS=~/.config/pithy/dash/tokens.json

# Create the environment itself. No click-through.
gh api -X PUT repos/$REPO/environments/staging

# The credential is a secret.
gh secret set CLOUDFLARE_API_TOKEN --repo $REPO --env staging \
  --body "$(jq -r '.staging.CF_TOKEN_CI_SYSTEM' $TOKENS)"

# The ids are not secrets. They are already committed in wrangler.jsonc.
gh variable set CLOUDFLARE_ACCOUNT_ID --repo $REPO --env staging --body "$ACCOUNT_ID"
gh variable set SECRETS_STORE_ID      --repo $REPO --env staging --body "$STORE_ID"

Get that split right. An account id and a Secrets Store id are not secrets — they sit in your wrangler.jsonc in the open — and filing them as secrets only renders them *** in the log you are reading to find out which account a run used. The token is the secret. The ids are variables.

Put production behind a GitHub environment with required reviewers while you are in there. It is one setting, and it is the difference between a merge and a deploy to the environment holding other people’s data.

It took ten failed runs over ten days to arrive at that short list, which is the honest part of this section. The one worth repeating: a value stored per machine, absent on the runner, made the affected Workers skip rather than refuse — and said so only in the JSON output. A silent skip is the expensive kind. It is a closed issue in the kit now, along with every other gap this build hit.

What is still awkward?

Two things, and you should know them before you start rather than after.

The cold start is slow, and almost all of it is one step. Before Vite serves a request it works out which classes your Worker exports, and it does that by importing the Worker’s entire module graph inside the runtime — one module at a time. On this project that is 303 modules at about 88ms each, which is 28 of the 30 seconds. It is round-trip latency rather than build work: Vite’s own transform across all 303 modules takes 2.3 seconds.

The React package is a template copier, not a component library. It writes your router, entry point and first screens, then it is done. No <Button>, no table, no layout. The design system is yours.

The part to take away

Do not buy an account until the local loop stops telling you anything new. Scaffold it, compose what you need, seed a database with people in it, and run the whole thing on your own machine while the questions are still about your product.

Then buy the account, spend an afternoon handing your pipeline the credentials it cannot borrow from you, and get on with it.