CLI and starter templates

Create a new site

Run the create command, choose a target directory, pick a starter template, then decide whether to write credentials, install dependencies, and initialize git.

pnpm create handover@latest my-client-site
# equivalent package form
npx create-handover@latest my-client-site

Choose a template

The CLI ships four bundled templates and a custom template option. Use the interactive picker for normal work or pass --template in scripts.

• next - App Router starter with embedded admin and auth flows
• vite-react - React + TypeScript starter with themed admin surfaces
• tanstack-start - route-driven starter with the same Handover admin contract
• astro - content-heavy starter with docs/blog routes and image-key rendering

pnpm create handover@latest my-site --template astro
pnpm create handover@latest my-site --template vite-react
pnpm create handover@latest my-site --template tanstack-start

Useful flags

Use flags when running the CLI from automation or when you already know the target framework and credentials.

• --list-templates prints bundled templates
• --api-url and --api-key write credentials into the scaffold env file
• --package-manager chooses pnpm, npm, yarn, or bun
• --install and --no-install control dependency installation
• --git and --no-git control repository initialization
• -y or --yes skips prompts and requires an explicit template

Agent context

Every scaffold includes .handover/context.json. Coding agents should read this file before changing generated sites because it records env names, template metadata, known site component slots, and preferred deploy commands.

The context remoteAuthEnv list only needs the project API URL/key for deploy workflows. Admin session credentials are still used by interactive admin APIs, but are not required for pnpm handover deploy.

Deploy from local content

After editing .handover/agents.json, Markdown files, blog posts, or local image assets, run pnpm handover deploy. The CLI reads the API URL/key from the scaffold env file and pushes through deploy endpoints protected by X-Handover-Api-Key.

pnpm handover deploy
pnpm handover deploy --manifest ./handover.content.json --mode merge
pnpm handover deploy --docs ./docs
pnpm handover deploy --blog ./blog
pnpm handover deploy --assets .handover/assets