@draftbase/create

Creates a working Astro or Next.js site from an official Draftbase example, signs you in, mints the API keys it needs, seeds the example's content types into your workspace, and optionally publishes it to a GitHub repo deployed on GitHub Pages. No dashboard clicking, no copy-pasting keys.

npx @draftbase/create my-site
# or: pnpm create @draftbase my-site
# or: yarn create @draftbase my-site

Node.js >= 20 and a TTY (it's an interactive prompt — it says so rather than hanging if piped).

Templates are fetched from each example repo's default branch at run time, so you always get the current version.

1. Asks which example to start from.
2. Opens your browser to sign in — the refresh token is cached in ~/.draftbase/credentials.json (mode 0600), so later runs skip this.
3. Asks which environment to use, if your workspace has more than one.
4. Creates a delivery key and a management key for that environment.
5. Offers to publish to a new public GitHub repo and deploy to GitHub Pages (only when the GitHub CLI is installed and authenticated).
6. Downloads the example, writes .env, installs dependencies, and creates the example's content types.
7. Opens the CMS on a new entry — the link carries ?org= and ?env=, so the workspace and environment switchers land on what was just provisioned.

Ctrl+C exits cleanly at any point.

The first non-flag argument is the target directory (npx @draftbase/create my-site).

.env gets both keys:

• DRAFTBASE_API_KEY — delivery-scoped, read-only, published entries only. This is the one that belongs in CI.
• DRAFTBASE_MANAGEMENT_API_KEY — can write and delete content. It exists so npm run seed works on your laptop, and should never reach a hosting provider or CI secret.

Answering yes to the deploy prompt creates the repo, sets DRAFTBASE_API_KEY as a repo secret (passed on stdin, never as a command-line argument), sets DRAFTBASE_ENVIRONMENT, SITE_URL and BASE_PATH as repo variables, points Pages at the shipped Actions workflow, and pushes. The push happens last so the first build already has everything it needs.

Rebuild-on-publish is the one manual step left: add a Draftbase webhook that POSTs a draftbase-publish repository_dispatch to your repo. The CLI prints the exact URL. It needs a GitHub token that only you can mint.

Once your keys are written to .env, no later step can lose them. A failed install, seed, or deploy is reported at the end with the command to retry, rather than aborting the run.

DRAFTBASE_API_URL and DRAFTBASE_APP_URL override the defaults (https://api.draftbase.co, https://draftbase.co).

If you're an agent setting up Draftbase in a new project:

1. This CLI is interactive and needs a TTY — it cannot be run headlessly. Hand the command to the user to run themselves; don't pipe input to it.
2. It creates a new directory from a template. For an existing project, install @draftbase/sdk and @draftbase/renderer directly instead.
3. Never commit .env — it holds a management key that can delete content. Confirm .env is gitignored before any commit.
4. Only DRAFTBASE_API_KEY goes into CI or a hosting provider. DRAFTBASE_MANAGEMENT_API_KEY is local-only.
5. Don't re-run it to fix a failed step — the CLI prints the exact retry command for whatever failed (install, seed, deploy); run that.

What is Draftbase? Draftbase is a lightweight, MDX-based headless CMS built for React and Next.js developers. Content is authored as MDX/markdown with typed fields, fetched via @draftbase/sdk, and rendered with @draftbase/renderer into React, Vue, or static HTML.

Do I need a Draftbase account first? No — the CLI opens your browser to sign in or sign up mid-run, then provisions the keys and content types for you.

Can I use it on an existing project? No — it scaffolds a fresh directory from an example. For an existing app, add @draftbase/sdk and @draftbase/renderer yourself.

Does it have to deploy to GitHub Pages? No, that prompt is optional and only appears when the GitHub CLI is installed and authenticated. The generated site is a normal Astro/Next.js project and deploys anywhere.

What if npm install or seeding fails? Nothing is lost — your project and keys are already on disk. The CLI reports the failure at the end with the command to retry.

Adding a new example is a single row in EXAMPLES in src/index.ts — the CLI knows nothing repo-specific beyond the conventions every example shares (a scripts/seed.mjs, a .env, an npm run dev). Two of those conventions exist for this CLI and must hold in every example:

• SEED_TEMPLATES_ONLY=1 makes scripts/seed.mjs stop after creating content types.
• SITE_URL / BASE_PATH env vars drive the site config, and deploy.yml forwards them from repo variables.

• npm
• Source
• Issues
• @draftbase/sdk — fetches the content the scaffolded site renders
• @draftbase/renderer — renders the MDX
• draftbase.co — product site
• Docs
• Framework support
• Pricing