Commands

Cusp is a pnpm project. You never need a terminal to run a Cusp site — the one-click deploy and the in-browser admin cover that — but deployers driving things from their own machine, and anyone hacking on Cusp or authoring a theme or plugin, use the commands below. They assume a clone of the repository, Node 20 or newer, and pnpm 9 or newer.

Provision and deploy

• pnpm install — install dependencies.
• pnpm cusp:bootstrap — provision the D1, R2, and KV resources in your Cloudflare account (idempotent — it only creates what is missing), wire the bindings, build, deploy, and ping the health endpoint to run the embedded migrations. The fastest way to stand up a deployment from your own machine. See the deploying guide.
• pnpm deploy — build and deploy the Worker to an already-provisioned deployment.

Local development

• pnpm dev — run the Worker locally with Wrangler against local D1, R2, and KV. Hot-reloads Worker code.
• pnpm dev:fresh — the same, but wipe local state first for a clean first-run wizard.
• pnpm dev:example — run the Worker locally against a separate persisted state (on port 8788), building the admin SPA first, so you can drive the example site without disturbing your main dev state.
• pnpm dev:example:fresh — the same, but wipe that separate example state first for a clean run.
• pnpm dev:admin — run the Astro dev server for the admin SPA on its own, with hot module reload, for fast iteration on admin UI without rebuilding the static bundle.
• pnpm db:migrate:local — apply the database migrations to the local D1 (the deployed Worker runs them automatically on first request, so this is only for local work).
• pnpm seed:example — seed the example site (the Royal Society of Pheasant Patissiers) into a running deployment.
• pnpm seed:docs — seed this documentation site's content into a running deployment.

Build and quality gate

Run pnpm verify before considering a change complete; it is the gate the project holds itself to.

• pnpm verify — the pre-commit gate: runs pnpm check, pnpm lint, and pnpm test in sequence. Green here is the bar a change must clear.
• pnpm build — build everything: migrations, the example-site bundle, the embedded themes and plugins, the admin SPA, and the Worker.
• pnpm build:size — measure the already-built Worker bundle's compressed size against the budget (3 MB on the free plan), so a heavy dependency cannot silently push it over the limit. Run after a build.
• pnpm check — type-check the Worker and the admin SPA.
• pnpm lint — run ESLint across the codebase.
• pnpm test — run the Vitest unit and integration suites (against Miniflare) and the script suite.
• pnpm test:e2e — run the Playwright end-to-end tests against a local dev server.

Theme and plugin authoring

• pnpm theme:keygen — generate an Ed25519 signing key pair for signing your own theme or plugin packages.
• pnpm theme:pack — compile a theme directory (TypeScript templates to JavaScript) and sign it into an installable tarball. pnpm theme:build is the underlying build-and-sign step for the first-party themes.
• pnpm theme:dev — watch a theme directory, repack on change, and install it into a local dev deployment for a live authoring loop.
• pnpm theme:embed / pnpm plugin:embed — regenerate only the embedded first-party bytes committed into the Worker, from the already-built dist tarballs. They do not build or sign anything themselves; run theme:build / theme:pack (or plugin:build) first to produce the tarballs these embed.

The theme authoring and plugin authoring guides walk through the signing and packaging flow in full.