pithy add turnstile --with-prerequisites--with-prerequisites composes secrets, which turnstile requires — the widget secrets are read through the registry.
What lands in your repo
apps/<worker>/pithy.config.ts gains the turnstile import and its registration, with a blank sitekey per environment for provisioning to fill:
turnstile({
// The widget login renders. `pithy turnstile provision` writes each environment's sitekey here, and the build inlines it.
widgets: { visible: { sitekeys: { dev: "", staging: "", prod: "" } } },
}),wrangler.jsonc gains nothing. This capability declares no required bindings. There is no database, no bucket, no namespace and no Workflow — nothing durable to bind.
No migrations run, because there are no tables. pithy add turnstile is the shortest add in the kit.
The one thing you configure
widgets declares which widget modes exist: visible, invisible, or both. Each mode you declare carries a sitekeys block with a string for dev, staging and prod. Leave them blank. pithy turnstile provision writes them, and it refuses a mode with no such keys to write into.
turnstile({
widgets: {
visible: { sitekeys: { dev: "", staging: "", prod: "" } },
invisible: { sitekeys: { dev: "", staging: "", prod: "" } },
},
}),That declaration is what pithy turnstile provision reads to know how many production widgets to create, and what the middleware’s mode option selects between when you run both.
There are no CLI flags for it, deliberately. A flag would be a second source of truth frozen at scaffold time, and it would drift the moment somebody enables a mode in config. The scaffolded front-end screens read the composed config for the same reason, through the client projection the build inlines.
Then provision
pithy turnstile provisiondev and staging get Cloudflare’s documented test secret, and production gets a real widget per declared mode, bound to your Worker’s production hostname, with its secret in the production store. Every environment’s public sitekey is written into this turnstile({ ... }) block in pithy.config.ts, and the account the widgets live in is recorded as turnstile-account. The build inlines the sitekeys, so redeploy staging and prod afterward.
There is no --env. A widget binds to the domain a human loads it on, so production is not a parameter — the hostname is resolved from the target Worker’s domains declaration, its route, or its BASE_URL. A Worker with none of the three is refused, naming the declaration to add.
A re-run reuses an existing production widget rather than creating a second one. Cloudflare never returns an existing widget’s secret, so it cannot be recomposed: a re-run leaves the stored secret exactly as it was and reports that it did. If the secret was never stored, re-running will not heal it — deprovision then provision is what does.
That is also the repair for a production gate answering turnstile/config:
pithy turnstile deprovision
pithy turnstile provisionpithy turnstile is the whole command surface.
Gate your first route
One import, one line:
import { turnstile } from "@pithy-sh/turnstile/src/http/middleware";
app.use("/signup", turnstile());Pass action where the route has a meaningful name — it binds the token to that route, so one solved elsewhere cannot be replayed against it. Pass mode when you run both widgets.
The gate reads the token from a copy of the body, so the handler behind it still reads the request as it arrived. For a JSON API or a native client that sends the token out of band, use header-token mode — turnstile({ header: "x-turnstile-token" }) — and the gate never reads the body at all.
And if auth is composed, you are already done
@pithy-sh/auth auto-gates its own magic-link and one-time-code send routes the moment turnstile is present. No wiring, no config, no route line to add. Those are the two routes a bot most wants, and they are covered by composition alone.
Check it worked
pithy doctor reports turnstile under the Worker’s health. In dev, a request without a token gets turnstile/missing_token and one with a test token passes — which is the fastest way to confirm the middleware is where you think it is.