Scaffold a new Pithy project: the root config, the gates CI needs, and its first Worker under apps/.
Synopsis
pithy init [--name <name>] [--worker <name>] [--target <mobile|web|both>] [--lint <biome|oxlint>] [--react-native | --no-react-native] [--app <name>] [--ios-rail <rail>] [--android-rail <rail>] [--web-rail <rail>] [--dir <path>] [--json]Flags
| Flag | Type | Default | Meaning |
|---|---|---|---|
--name <name> | string | the target directory’s name | Project name. Leads every Cloudflare resource this project provisions |
--worker <name> | string | api | Name of the first Worker, created at apps/<name> |
--target <target> | string | mobile | Which clients call this backend: mobile, web or both. web and both scaffold a React front end into the first Worker |
--lint <linter> | string | biome | Which linter runs the kit’s lint safeguards: biome or oxlint. oxlint keeps Biome as the formatter |
--react-native / --no-react-native | boolean | asked; no when nobody may be asked | Add an Expo app for iOS, Android and the web in its own apps/<name>, calling the first Worker. mobile and both targets only |
--app <name> | string | app (mobile when the Worker is app) | The Expo app’s directory. Passing it asks for the app |
--ios-rail <rail> | string | none | The rail the iOS app sells through: apple, stripe, lemonSqueezy, paddle or none. Passing it asks for the app |
--android-rail <rail> | string | none | The rail the Android app sells through: google, stripe, lemonSqueezy, paddle or none. Passing it asks for the app |
--web-rail <rail> | string | none | The rail the web build sells through: stripe, lemonSqueezy, paddle or none. Passing it asks for the app |
--dir <path> | string | . | Target directory. Created if missing; must not already hold the files init writes |
--json | boolean | false | Machine-readable output. Also suppresses every prompt |
What it does
It checks the target first, before a single question is asked, so a doomed run fails fast rather than after you have answered everything.
This is the first command of the quickstart, and everything below is what it does when you run it somewhere that is not an empty directory.
The check is collision, not emptiness. A directory holding only .git, a README, a license or an editor config is not a project, and refusing it would mean pithy init could not scaffold into a repo you just cloned — which is how projects normally start. It refuses only if something init would write is already there. The two paths the scaffold moves rather than copies — apps/api, and apps/<worker> when --worker is not the default — are held to emptiness instead, because a rename is not a merge.
It asks the names, when a human is attached and a flag did not supply them.
The project name comes with the reasoning printed above it, because both halves of it are hard to undo: the name leads every Cloudflare resource this project provisions, teardown recomputes those names rather than storing them, and the scope decision behind it — one project or two? — cannot be fixed by editing a string later. One project per set of apps that share users or data. Another app is another Worker, not another project.
The first Worker is named too, because every Worker lives in apps/<name> and api is only a default.
It asks which environments this project deploys to. ["staging", "prod"] is offered as the default, so one keypress is the whole answer.
It is asked here for the same reason the project name is. <project>-<env>-<thing> has a 33-character ceiling, name is capped at 26 against it, and the environment is the other segment of that budget — it sits in the middle of every Cloudflare name this project will compose. Like name, it is effectively permanent: renaming an environment does not rename anything provisioned under the old one, it orphans it. What you answer is written into each Worker’s env.<name> stanzas, and — only when it differs from the default — into the root pithy.config.ts as environments. An answer the naming rule refuses is re-asked rather than accepted, and dev is refused outright, because it is local, always present, and never deployed.
It asks which clients call this backend: mobile apps, a web app, or both. The answer decides whether the first Worker also serves a front end.
The backend is the same either way. Auth already speaks both dialects — bearer tokens for a device, a CSRF-protected cookie for a browser — so only what the Worker serves beside its routes differs. mobile, the default, scaffolds the API alone, which is what init has always written. web and both add a React front end to the first Worker exactly as pithy ui add react would, with no screens yet, because a new project composes nothing to sign in to. Run pithy ui add react again once a capability with screens is composed: it adds them and leaves every file already there as it is.
The front end’s dev command runs through the package manager that launched pithy — bunx, pnpm dlx, npx or yarn dlx — and, with none, through npm until the first install writes a lockfile. Re-running pithy ui add react then rewires it. An answer that is not one of the three is refused before anything is asked.
It asks which linter runs the kit’s lint safeguards: Biome or Oxlint. The same rules either way, with the same names, the same matches and the same messages: no-console and no-process-io keep a Worker’s logs queryable, no-raw-request-input and no-bare-zvalidator keep every route’s request contract on the route line where pithy contract reads it, no-raw-use-effect keeps a screen’s effects in hooks named for what they sync with, no-z-config keeps a locale inside its request, and no-unerasable-syntax keeps each pithy.config.ts and each Worker’s own .ts source loadable by Node’s type stripping, which is how the CLI reads the config and every module it imports. Each is scoped to your layout — the Worker’s own source under apps/*/src — with the hooks pithy ui add writes excluded by name from no-raw-use-effect, and every pithy.config.ts covered as well by no-unerasable-syntax, which skips tests and .d.ts files.
no-unerasable-syntax refuses TypeScript that compiles to code rather than erasing: an enum, a constructor parameter property, import x = require(...), export =, and an angle-bracket assertion <T>value. It refuses every namespace too: Node refuses one with a value in it, and the rule refuses them all so it never has to decide which kind it is looking at. Ambient declarations and import type x = require(...) erase, so they pass. Without the rule, tsc, Vitest and the Worker’s bundler all accept such a module, and every command that loads the config refuses it, naming the file, the line, the construct and its rewrite. A module the config imports from outside the rule’s scope — a .tsx file, a file elsewhere under the Worker such as apps/<worker>/lib/, or another workspace package’s source — is loaded the same way and is not checked, so keep those free of the same syntax or widen the rule’s includes.
biome, the default, writes them as GritQL rules in plugins/*.grit, with an entry for each in biome.jsonc. oxlint writes them as one Oxlint JS plugin, plugins/pithy.oxlint.js, and an .oxlintrc.json that loads it with one override per rule, covering exactly the files the Biome entries cover. Biome stays in an Oxlint project as the formatter and keeps its recommended lint rules, so biome.jsonc is still written, without its plugins; the lint script becomes biome check . && oxlint, and oxlint is pinned in devDependencies. Oxlint’s JS plugin API is alpha and outside semver; none of the rules needs type information, which it does not support. An answer that is not one of the two is refused before anything is asked.
The rules are written at init and nowhere else. pithy upgrade and pithy ui add write no lint rules, so a project scaffolded before a rule shipped, or one switching linters, copies the files by hand from the starter in @pithy-sh/cli’s templates/starter: the .grit files and their plugins entries from biome.template.jsonc, or plugins/pithy.oxlint.js and oxlintrc.template.json, saved as .oxlintrc.json.
It offers a React Native app, to a mobile or both target: Add a React Native app for iOS, Android and the web?, defaulting to no. A yes writes an Expo app into apps/app/ exactly as pithy ui add react-native would, calling the first Worker, with no screens and every rail none, because the new Worker composes nothing yet. The app runs its own screen tests with Vitest: apps/app/vitest.config.ts on nativeTestProject from @pithy-sh/ui-react-native/testing/vitest, a test script (vitest run), and one test, src/routes/app/home.test.tsx, which checks the home screen asks the Worker’s health route on the web and on iOS. The root vitest.config.ts leaves the app to that config. mobile still means an API-only Worker unless you say yes, and a run that may not ask adds no app. --react-native says yes without the question, and so does --app or any rail flag; --no-react-native says no. Asking for the app on a web target is refused. A rail flag is held to the new Worker before anything is written, and that Worker enables no rail, so only none passes: enable a rail in the Worker’s pithy.config.ts, then set it with pithy ui sync --app app --ios-rail apple.
It writes the scaffold. The root pithy.config.ts, the root package.json, biome.jsonc, .gitignore, the .dev.vars.example and .dev.secrets.example.jsonc templates, the lint safeguards for the linter chosen above, and the configs CI gates on — tsconfig.json (a solution file), tsconfig.tools.json, vitest.config.ts and vitest.workers.config.ts.
Then apps/<worker>/ with its own pithy.config.ts, wrangler.jsonc, pithy.worker.jsonc, tsconfig.json, package.json, src/index.ts, src/cloudflare-test.d.ts, and a src/bindings.workers.test.ts that runs against real D1 and KV through Miniflare.
It writes the agent instructions. Straight after the scaffold, before any question that can be canceled, so a project never exists without them. AGENTS.md gets a marked Pithy block telling the agent working in this project how to drive the CLI: pithy schema --json, PITHY_JSON=compact, PITHY_NONINTERACTIVE=1, --dry-run before a change, the exit codes, that pithy remove and every typed confirmation phrase are a person’s, the describeRoute fields that make an app route an MCP tool for its users’ agents (operation, tool, power), and that a person connects a deployed environment with pithy mcp connect --scope manifest:read plus only the reads needed, and disconnects it with pithy mcp disconnect. CLAUDE.md gets one line importing it — Agent instructions for this project, Pithy’s included: @AGENTS.md — because Claude Code reads its own file and not the shared one.
Either file is created when the target has none. When a cloned repository brought its own, every byte of it stays and the block, or the line, is appended after a blank line — so neither file is ever a collision. A CLAUDE.md that already imports @AGENTS.md, or that is a link to AGENTS.md, is left alone. A symlinked file, or an AGENTS.md whose markers are already there and broken, is refused and said so, and the scaffold still completes. pithy upgrade refreshes the block from then on.
It records your Cloudflare credentials and discovers the account. This is the one moment you are holding the token, which is why it belongs here: listing zones two prompts later needs it, and so does every command after this.
The token is written to <config>/cloudflare.<name>.json — mode 0600, in a 0700 directory, outside every checkout. Nothing secret goes into your project. The account is discovered rather than asked for: the token lists the accounts it can see, one is a confirmation and several are a picker, and choosing the account supplies both its id and the nickname for its credentials file. A narrowly scoped token that cannot list falls back to asking for an account id, and init still completes.
What lands in pithy.config.ts is at most a cloudflare block naming the account — its nickname, and, if you accept the offer, the account id as a pin. An account id is an identifier rather than a secret, and pinning it is what stops another machine’s nickname from meaning a different account.
Press enter to skip the whole thing, and sign in afterwards with pithy cloudflare connect: no token to make by hand, and the account is discovered the same way. Until one or the other is set, pithy doctor names the sign-in.
It asks where the Worker answers, against that account’s real zones. Skippable: a project without a domain yet is legitimate, and adding one later is a config edit plus a deploy. What you declare is written into the Worker’s pithy.config.ts as a domains block, and generated from there into its wrangler.jsonc routes entry and vars.BASE_URL.
It offers the p. shortcut, then tab completion, each once, at the end, and only to a human at a terminal. A yes to the second installs pithy completion into the same rc file, and it covers p. too.
A block the writer could not place is printed for you to paste, never dropped. That applies to both the cloudflare block and the domains block: guessing at the shape of a file somebody may already have edited is how a scaffold eats an edit.
Nothing here is prompted under --json, --no-input, PITHY_NONINTERACTIVE=1, or without a TTY. Every question has a default, so a run that may not ask takes it rather than failing. Not the names, not the environments, not the target, not the linter, not the React Native app, not the credentials, not the domains, not the alias, not completion. A CI run scaffolds with the flags it was given, takes the default environments and writes no environments line, takes mobile unless --target says otherwise and biome unless --lint does, and writes no cloudflare block.
--json
One line, one object.
$ pithy init --name replay --worker board --json
{"command":"init","schemaVersion":1,"targetDir":"/home/you/replay","appName":"replay","worker":"board","environments":["staging","prod"],"target":"mobile","lint":"biome","frontEnd":null,"reactNative":null,"domains":null,"agents":{"path":"AGENTS.md","state":"added","reason":null},"claude":{"path":"CLAUDE.md","state":"added","reason":null}}| Key | Type | Meaning |
|---|---|---|
command | "init" | The command that produced the line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
targetDir | string | The absolute directory scaffolded into — --dir resolved against the working directory |
appName | string | The project name written into the root pithy.config.ts as name. From --name, or the target directory’s basename |
worker | string | The first Worker’s apps/ directory. What --worker accepts, and what --worker on later commands names |
environments | string[] | Every environment this project deploys to, in declaration order. Always ["staging","prod"] under --json, because declaring anything else is a prompt |
target | string | Which clients call this backend: mobile, web or both. mobile under --json unless --target says otherwise, because asking is a prompt |
lint | string | The linter the lint safeguards were written for: biome or oxlint. biome under --json unless --lint says otherwise, because asking is a prompt |
frontEnd | object or null | The front end scaffolded into the first Worker, or null for a mobile target |
frontEnd.framework | string | The framework scaffolded. react |
frontEnd.created | string[] | The Worker-relative files it created, sorted |
reactNative | object or null | The Expo app scaffolded beside the first Worker, or null when none was added. null under --json unless --react-native, --app or a rail flag asks for it, because the offer is a prompt |
reactNative.app | string | The app’s apps/ directory |
reactNative.created | string[] | The app-relative files it created, sorted |
reactNative.rails | object | { ios, android, web }: the rail each platform sells through. none everywhere, since the new Worker enables no rail |
domains | object or null | Where that Worker answers, per environment, or null when none was declared. Always null under --json, for the same reason |
domains.staging | object | Where the Worker answers in staging, if it has a domain yet |
domains.staging.pattern | string | The hostname, e.g. api.example.com. A bare hostname rather than a URL — that is what wrangler’s route matcher takes |
domains.staging.zone | string | The Cloudflare zone the pattern sits under, e.g. example.com. Cloudflare needs it to attach a custom domain, and it is not always derivable from the hostname |
domains.prod | object | Where the Worker answers in prod, if it has a domain yet |
domains.prod.pattern | string | The hostname, as above |
domains.prod.zone | string | The zone it sits under, as above |
agents | object | AGENTS.md, and what happened to the Pithy block in it |
agents.path | string | "AGENTS.md", relative to the project root |
agents.state | "added", "updated", "unchanged" or "refused" | added — the block was written, into a new file or after the text of one the repository brought. updated and unchanged — the repository already carried a Pithy block, and it was rewritten or was already current. refused — nothing was written, and reason says why |
agents.reason | string or null | Why it was refused, in one line that never quotes the file. null otherwise |
claude | object | CLAUDE.md, and whether it now imports AGENTS.md |
claude.path | string | "CLAUDE.md", relative to the project root |
claude.state | "added", "unchanged", "linked" or "refused" | added — the line was written. unchanged — it already imported @AGENTS.md. linked — it is the same file as AGENTS.md, through a symlink either way. refused — not written, and reason says why |
claude.reason | string or null | Why it was refused. null otherwise |
domains is reported with the shape it takes in pithy.config.ts, so a --json consumer and a hand-written config describe the same thing. Both environment keys are optional — a project with staging wired and production not is legitimate. dev is absent by design: local runs answer on http://localhost:<port> from the port pinned in .dev.config.json.
The line carries no cloudflare block. The account’s nickname and id go into pithy.config.ts, and the credentials go outside the repository. Neither is echoed, because a token in a terminal is a token in a scrollback and a CI log.
Errors
Each one is a problem line then an action line. Under --json it is a single {"error":{…}} line on stderr, with exit, retryable and, where the cause is known, fix, and the process exits by its class — 2 for a call to fix, 3 for something in the way. An AGENTS.md or CLAUDE.md that cannot be merged into is not one of these: the scaffold completes, the file is left as it was, and the run says so in one line.
Something init would write is already there. The collision list names every path, sorted.
$ pithy init
/home/you/replay already has .gitignore, apps/board, package.json, pithy.config.ts, tsconfig.json, ….
Move those aside, or pick a directory without them, then run this again.A Worker name that is not kebab-case. Validated before any path is built out of it.
$ pithy init --worker "Bad Name"
Worker name must be kebab-case (got "Bad Name").
Use lowercase words joined by hyphens, e.g. api or admin-api.A target that is not one. Refused before the first question, so a typo does not cost the answers after it.
$ pithy init --target desktop
"desktop" is not a target.
Pass --target mobile, web or both.A linter that is not one. Refused the same way, before the first question.
$ pithy init --lint eslint
"eslint" is not a linter.
Pass --lint biome or oxlint.A React Native app on a web target. Exit 2, before the first question.
An --app name the app cannot take. Exit 2, validation/invalid_input, before anything is written: a name that is not kebab-case, or the first Worker’s own name.
A rail the new Worker does not enable. Exit 3, core/precondition_failed, before anything is written. The new Worker composes no payments, so the action is the pithy add payments fix. A value no platform takes is exit 2, listing the ones it does.
$ pithy init --ios-rail apple
The apple rail needs the payments capability, and api doesn't compose it.
Run `pithy add payments --worker api --with-prerequisites --set billingSubject=user` or `pithy add payments --worker api --with-prerequisites --set billingSubject=organization` and enable rails.apple, or pass --ios-rail none.A project name over 26 characters. The name sits at the front of every Cloudflare name the project composes, and a provisioned project cannot be renamed, so the limit is enforced at the scaffold rather than at the first provision.
$ pithy init --name this-is-a-really-long-project-name
"this-is-a-really-long-project-name" is 34 characters. A project name stops at 26.
Shorten `name` in pithy.config.ts to 26 characters or fewer.Naming rules and limits derives that number.
A symlink or a non-directory in the way. Refused at every segment of the path, rather than left to die on a raw ENOTDIR with the run half-written.
A name in the reserved test namespace. Refused before anything is written — the debris reaper deletes on that prefix alone.
A canceled prompt. Canceled. on stderr, exit 130. Nothing proceeds on a value you did not choose.
Examples
Scaffold into the current directory, answering the prompts.
$ pithy init
One project per set of apps that share users or data. Another app? Add a worker, not a project.
The name leads every Cloudflare resource this project provisions. Changing it later orphans them.
Project name: replay
First worker (apps/<name>): board
…
AGENTS.md: Pithy block added.
CLAUDE.md: points at AGENTS.md.
Done.
Want a shortcut? Type `p.` instead of `pithy`.
Want tab completion for `pithy`?Answering yes installs the alias silently — its own Added … and Open a new terminal … lines are the only output. See pithy alias.
The second question is asked once, after the first, with the same rules. Answering yes installs tab completion into the same rc file, silently in the same way. With the p. shortcut installed, completion covers p. too. See pithy completion.
Scaffold headlessly. Both names given, so nothing is asked.
pithy init --name replay --worker board --jsonScaffold for a web app. The first Worker serves a React front end beside its routes.
$ pithy init --name replay --worker board --target web
…
A React front end is in apps/board/.
Run pithy setup, then pithy dev.
…Scaffold for phones, with an Expo app beside the API.
$ pithy init --name replay --react-native
…
An Expo app is in apps/app/. It calls api.
Run pithy setup, then pithy dev.
…Scaffold into a directory that does not exist yet. It is created.
pithy init --name relay --worker deck --dir apps-relayThen make the checkout ready, and run it. pithy setup installs with the package manager that launched pithy, mints the local secrets, migrates and seeds dev, and pins the ports; pithy dev starts every Worker.
pithy setup
pithy devThe project name and the Worker name are different things, and it is worth keeping them different. replay is the project; board is one of its Workers; the Worker deploys as replay-board, and staging suffixes that again. Add the next Worker with pithy worker add, not a second pithy init.