CLI Reference
This is the one authoritative command reference. Other pages link here.
Summary
Section titled “Summary”| Command | Run in | Needs |
|---|---|---|
npm create @kenresoft-cms@latest [dir] |
Anywhere | git |
npm create @kenresoft-cms@latest [dir] -- --astro |
Anywhere | none |
npx @kenresoft-cms/create astro [options] |
An Astro project | An Astro 5+ project |
pnpm run setup |
CMS project | Wrangler login |
pnpm run update [-- flags] |
CMS project | A completed setup |
pnpm run rename-worker -- --target … --name … |
CMS project | A completed setup |
pnpm --filter @kenresoft-cms/api recover-owner:remote |
CMS project | Wrangler access to the account |
pnpm --filter @kenresoft-cms/api backup-media / restore-media |
CMS project | Wrangler access |
Create
Section titled “Create”npm create @kenresoft-cms@latest [dir]
Section titled “npm create @kenresoft-cms@latest [dir]”Purpose: create a CMS project. Clones the CMS repository’s default branch with real Git history and upstream as the remote name. dir must be empty or omitted (then the current directory must be empty).
Changes: creates files in dir. Does not: provision anything in Cloudflare. Next: pnpm install, then pnpm run setup.
npm create @kenresoft-cms@latest [dir] -- --astro
Section titled “npm create @kenresoft-cms@latest [dir] -- --astro”Purpose: create a standalone Astro starter for an existing CMS. Copies a bundled template and starts a fresh Git repository with no upstream. Requires a CMS URL afterwards (PUBLIC_KENRESOFT_CMS_URL). It is never updated by pnpm run update.
npx @kenresoft-cms/create astro
Section titled “npx @kenresoft-cms/create astro”Purpose: connect an existing Astro project (5+) to a CMS. Run from the project root. Does not require a CMS repository and does not touch a CMS.
| Option | Effect |
|---|---|
--cms-url <url> |
CMS API URL (http or https) |
--no-install |
Edit package.json only; you install |
--update |
Refresh the managed files and package. Needs an existing .kenresoft/integration.json |
--force |
Replace edited managed files (with --update, or over a conflict) |
--dir <path> |
Target another directory |
--help, -h |
Usage |
Changes: the @kenresoft-cms/astro dependency, src/pages/cms/[...path].ts, src/lib/kenresoft.ts, .kenresoft/integration.json, and (first run only) PUBLIC_KENRESOFT_CMS_URL in .env and .env.example. Never changes: your pages, layouts, components, styles, Astro or Wrangler config, or the CMS. Exit codes: 0 ok, 1 error, 2 conflicts. See Existing Astro site.
CMS project
Section titled “CMS project”pnpm run setup
Section titled “pnpm run setup”Purpose: first deployment. Provisions D1 and R2, applies migrations, sets BETTER_AUTH_SECRET, optionally configures email, deploys the API and Admin Workers, and wires BETTER_AUTH_URL, ADMIN_URL and CORS_ORIGINS. Requires: Wrangler login. On an existing install: shows status and a menu, and never overwrites a real BETTER_AUTH_URL, rotates the secret without confirmation, or re-creates existing resources. See Set up.
pnpm run update
Section titled “pnpm run update”Moves the deployment to a newer release. Run inside the CMS project after setup has completed once. Pass flags after --.
| Command | Pulls code | Installs | Migrates | Deploys | Changes secrets or config |
|---|---|---|---|---|---|
pnpm run update |
Yes, the latest release | Yes | Yes | API and Admin | No |
pnpm run update -- --version <x.y.z> |
Yes, that release (never an older one) | Yes | Yes | API and Admin | No |
pnpm run update -- --branch <name> |
Yes, that branch | Yes | Yes | API and Admin | No |
-- --auth |
No | No | No | API, then Admin rebuilt | BETTER_AUTH_URL |
-- --email |
No | No | No | API | EMAIL_PROVIDER, EMAIL_FROM, RESEND_API_KEY |
-- --domain |
No | No | No | API | API custom domain route |
-- --admin-domain |
No | No | No | Admin, then API if CORS changed | Admin domain route, ADMIN_URL, CORS_ORIGINS |
-- --turnstile |
No | No | No | API, only if the site key changed | TURNSTILE_SECRET_KEY, TURNSTILE_SITE_KEY |
-- --storage |
No | No | No | No | Nothing (status only) |
-- --database |
No | No | No | No | Nothing (status only) |
- One category flag per run.
--versionand--branchcannot be combined with each other or with a category flag.UPDATE_BRANCHsets a default branch, for test installs only. --ciruns a category flag non-interactively, readingBETTER_AUTH_URL_NEW,EMAIL_PROVIDER_NEW,EMAIL_FROM_NEW,RESEND_API_KEY_NEW,CUSTOM_DOMAIN_NEW,DISABLE_WORKERS_DEV,ADMIN_CUSTOM_DOMAIN_NEW,TURNSTILE_SECRET_KEY_NEW,TURNSTILE_SITE_KEY_NEWandTURNSTILE_DISABLE. An unset variable means leave unchanged.- Safety checks: refuses without a
database_id, and refuses to deploy over a Worker bound to a different database.
See Update the CMS.
pnpm run rename-worker -- --target <api|admin> --name <new-name>
Section titled “pnpm run rename-worker -- --target <api|admin> --name <new-name>”Purpose: rename a Worker. Cloudflare cannot rename in place, so it deploys a new Worker under the new name, updates every cross-reference (admin build, BETTER_AUTH_URL, CORS_ORIGINS, ADMIN_URL), confirms before acting, checks the name is not held by an unrelated Worker, and offers to delete the old Worker. The old one keeps running until you delete it.
Recovery and backup helpers
Section titled “Recovery and backup helpers”Run from the CMS project. recover-owner:local/recover-owner:remote reset the Owner’s password with wrangler d1 execute (see Recovery). backup-media and restore-media copy R2 objects (see Backups).
Repository tasks
Section titled “Repository tasks”pnpm install, pnpm dev, pnpm build, pnpm test, pnpm run test:scripts, pnpm lint, pnpm typecheck, pnpm clean.