create-headroom-site

Scaffold a new Headroom CMS frontend site (Astro or Next.js), pre-wired to an existing Headroom install.

Usage

Interactive (prompts for framework, admin URL, login, and site):

pnpm create headroom-site

Pass the project directory as a positional argument to skip the first prompt:

pnpm create headroom-site my-app

Non-interactive / CI

With --admin-url, --email, and either --password or --password-stdin, the scaffolder runs without prompts. Alternatively, pass a pre-provisioned --api-key to skip admin login and key creation entirely.

| Flag | Description | |------|-------------| | --directory <path> | Project directory (positional also accepted) | | --framework <name> | astro or nextjs | | --admin-url <url> | Headroom admin URL or API URL | | --media-url <url> | Headroom media CDN URL (skips discovery fallback prompt) | | --email <email> | Admin email | | --password <password> | Admin password (visible in shell history) | | --password-stdin | Read admin password from stdin | | --site <host> | Site host to use (skips selection prompt) | | --api-key <key> | Pre-provisioned API key (skips login / key creation) | | -h, --help | Show this help |

Fully non-interactive, piping the password from stdin (keeps it out of shell history):

echo "$PASSWORD" | pnpm create headroom-site my-app \
  --framework astro \
  --admin-url https://headroom-admin.example.com \
  --email [email protected] --password-stdin \
  --site mysite.com

Bring your own API key (skips admin login and key creation):

pnpm create headroom-site my-app \
  --framework astro \
  --admin-url https://api.example.com \
  --site mysite.com \
  --api-key headroom_xxxxx

What It Does

1. Resolves the admin / API URL from --admin-url via a discovery document (also picks up the media CDN URL; falls back to a prompt or --media-url on older deploys).
2. Logs in as an admin with your email + password — or, with --api-key, takes the pre-provisioned key and skips login entirely.
3. Picks or creates the target site (from --site or an interactive selection).
4. Issues a bootstrap-<framework>-… API key on that site (login path only).
5. Copies the framework template into the project directory.
6. Writes .env with HEADROOM_API_URL, HEADROOM_MEDIA_URL, HEADROOM_SITE, and HEADROOM_API_KEY.
7. Runs git init in the new project (best-effort — a missing git binary logs a warning and never aborts the scaffold).
8. Writes .headroom/ credentials so the headroom CLI works from inside the project: a config.json pinning the URLs, active site, and CDN key, plus (in the login path) a 0600 token file holding the refresh token.

Generated Project Structure

my-app/
├── .devcontainer/
│   └── devcontainer.json   # Ready-to-test container with pnpm + Playwright CLI
├── .headroom/              # CLI credentials (gitignored) — config + refresh token
├── .env                    # HEADROOM_* connection vars (written at scaffold time)
├── .env.example            # Committed template of the connection vars
├── .gitignore
├── CLAUDE.md               # Full project guide (framework specifics, workflows)
├── package.json
├── src/                    # Pages, components, layouts, SDK client
└── scripts/
    └── generate-schemas.*  # Generate typed content schemas from the CMS

See the generated CLAUDE.md for the full guide to the project — its layout, data flow, and framework-specific workflows.

Next Steps

cd my-app
pnpm install
pnpm dev

Or open the project in the included devcontainer — it provisions Node, pnpm, and the Playwright CLI + browsers on create, so the dev server and browser tests run out of the box.

pnpm exec headroom whoami works immediately because the scaffolder saved your connection settings to .headroom/ — and, if you logged in as an admin, your refresh token too. (In the --api-key path no admin token is written; whoami still runs and reports the saved connection, just without an authenticated admin session.)

Prerequisite: git. The scaffolder runs git init, and the headroom CLI resolves its .headroom/ config from the git root. If git was not installed when you scaffolded (the git init step was skipped with a warning), run git init in the project before using the CLI so it finds the credentials.

Security: .headroom/ holds a refresh token. It is gitignored (both by the project .gitignore and by .headroom/.gitignore), so it stays out of commits. If you force-add it, you are committing a credential that grants admin access — don't.

Frameworks

• Astro — content-focused static/SSR site; dev server on port 4321.
• Next.js — React App Router site; dev server on port 3000.

Choose interactively or with --framework astro / --framework nextjs.

License

PolyForm Noncommercial 1.0.0