Install

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

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 add --global @pithy-sh/cli

npm install --global @pithy-sh/cli

pnpm add --global @pithy-sh/cli

yarn global add @pithy-sh/cli

Bun 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.

The p. shortcut

Two characters, ending in the mark:

pithy alias

That writes a delimited block into your shell’s rc file — ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, ~/.config/nushell/config.nu, or your PowerShell profile — 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.

Where Pithy keeps things on your machine

Nothing secret goes in your repository. One directory per machine holds it instead, resolved in this order:

1. $PITHY_CONFIG_DIR, if set
2. %APPDATA%\pithy on Windows
3. $XDG_CONFIG_HOME/pithy
4. ~/.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 pithy init will offer to record the credentials then, because that is the one moment you are already holding the token. It writes them to the config directory, discovers which account the token can see, and asks nothing further. Cloudflare API tokens covers which token to make and how little it needs to be allowed to do.