There is one tool to install and one version floor to clear. Everything else — wrangler, the Workers types, the test runner — arrives inside the project pithy init scaffolds, so you do not install it and you do not choose its version.
What you need first
| Version | Why | |
|---|---|---|
| Node.js | 22.18 or newer | The CLI’s floor, declared in its engines.node. It loads your TypeScript pithy.config.ts with Node’s own type stripping, which runs without a flag from 22.18. The published packages declare 22, the floor TypeScript 7’s compiler needs and Workers’ own compatibility surface is at parity with |
| Bun | 1.4 or newer, optional | Faster, and it runs TypeScript with no transpiler. The kit is built and tested with 1.4.3. Your project is not required to use it, but on an older Bun, upgrade Bun to 1.4.3 |
| A Cloudflare account | — | Only when you deploy. The Quickstartneeds none |
| git | any | For pithy feature, which runs worktrees. Not needed to scaffold |
Node 20 is not supported, and the reason is worth one sentence: tsgo, TypeScript 7’s Go-based compiler, requires Node 22, and holding the whole toolchain back for a shrinking minority costs everyone else more than it saves them.
Install the CLI
Install it globally. It is a development tool, not a dependency of your Worker — nothing it does ships to production.
- Bun
- npm
- pnpm
- Yarn
bun add --global @pithy-sh/clinpm install --global @pithy-sh/clipnpm add --global @pithy-sh/cliyarn global add @pithy-sh/cliBun is listed first because the kit is a Bun project, not because the others are second-class. The published packages are pure ESM with no Bun-specific runtime calls, and they run on Node 22, Bun, Deno and Workers alike. The CLI detects which package manager your project uses from its lockfile — bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json, npm when there is none — and runs installs with that one.
Check it
pithy --version--version works anywhere --help does, including after a subcommand.
Once you have a project, pithy doctor is the more useful check. It reports what is composed, what is bound, what is missing, and — because nothing in your repository mentions them — the resolved paths of the config directory on every run.
Point your agent at the docs
An AI agent working in your repository answers from its training data, which is a snapshot taken before whatever shipped this month. pithy docs connect points it at the documentation server instead, so it reads the current capabilities, config surface and naming rules rather than recalling an older shape of them.
pithy docs connectThe server is https://pithy.sh/mcp. Ten clients are known — Claude Code, Cursor, Visual Studio Code, Gemini CLI, Claude Desktop, Cline, Zed, Codex CLI, Goose and Continue — across four config syntaxes and five root keys, and the command writes each one in its own vocabulary. --all connects every client it detects on this machine; --client <id> writes the one you name whether or not it was detected.
It merges, and it refuses on doubt. The entry is written under the name pithy, and that is the only name it sets or removes; your own MCP servers, your comments, and the session state Claude Code keeps beside them are read, kept and written back unchanged. A document it cannot parse with confidence is left byte-identical on disk, and the snippet to add by hand is printed instead. A re-run reports unchanged and does not reopen the file.
pithy docs status reports what is connected and pithy docs disconnect takes it back out. pithy docs connect --print writes nothing anywhere and emits the snippet — for a named client, or the generic shape for a tool the table has never heard of.
Nothing written carries a credential, and no code path reads one. The server runs the standard MCP OAuth flow and registers clients dynamically, so a capable client reaches an authorized session from the URL alone and opens a browser on first use. Claude Desktop is the single exception: its config file takes stdio servers only, so that row is written through npx -y mcp-remote, and you quit and reopen the app for it to load.
pithy init offers the connection at the end of an interactive run when it finds clients, and says nothing when it finds none. pithy doctor lists any detected client with no entry, one line each, and never changes its exit code over it. pithy docs is the command page, and driving your AI with the docs is what to point it at once it is connected.
The p. shortcut
Two characters, ending in the mark:
pithy aliasThat writes a delimited block into your shell’s rc file — ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, ~/.config/nushell/config.nu, or your PowerShell profile, which on Windows means both PowerShell 7’s and Windows PowerShell 5.1’s — so p. add auth works after a reload. pithy alias --status reports it, pithy alias --remove takes it back out. pithy init offers it once, at the end, and only to a human at a terminal.
Tab completion
Commands, flags, environments, capabilities and your project’s Workers complete on Tab, in bash, zsh, fish and PowerShell:
pithy completionIt writes its own block into the same rc file pithy alias uses, and covers p. too. The script asks the installed binary on every Tab and never reaches the network, so it never goes stale. It needs pithy on your PATH, which the global install above gives you: bunx pithy and npx pithy complete nothing. pithy init offers it once, after the shortcut. pithy completion is the command page.
Where Pithy keeps things on your machine
Nothing secret goes in your repository. One directory per machine holds it instead, resolved in this order:
$PITHY_CONFIG_DIR, if set%APPDATA%\pithyon Windows$XDG_CONFIG_HOME/pithy~/.config/pithy
It is created 0700, with 0600 files, and it holds your Cloudflare credentials, your dev secret values, the machine-wide port registry, and the update notifier’s state. That placement is the reason several projects and several worktrees of each can run at once without a per-checkout setup step, and the reason rm -rf on a clone destroys nothing you would miss. The Pithy config directory is the whole story, file by file.
Do you need a Cloudflare account yet?
Not for the next page. pithy init scaffolds, pithy dev boots the Worker locally through Miniflare, and pithy migrate --env dev runs your schema into a local SQLite file. None of that touches an account.
You need one the moment you provision or deploy, and then you sign in rather than make a token: pithy cloudflare connect opens Cloudflare in your browser, asks for exactly what this project needs, and keeps the session in the config directory. No wrangler login either. If you already hold an account token, pithy init offers to record it instead, and Cloudflare API tokenscovers both and how little each needs to be allowed to do.