LumiBaseDocs

LumiBase CLI

lumibase — the JS/TS client and the CLI in one package: generate types from a live schema, check your setup, scaffold a project.

The unscoped package lumibase (packages/cli/) is both a library and a CLI. Its library entry (src/lib.ts) re-exports @lumibase/sdk, so a project needs one name in dependencies for the runtime client and the lumibase command:

bash
npm install lumibase
ts
import { createLumiClient, readItems } from 'lumibase';

@lumibase/sdk stays the underlying package — lumibase depends on it rather than bundling it, so a project that imports both gets one copy of every class (LumiError instanceof checks) and one set of types. The library entry has no Node-specific code and is safe to import from browser and edge bundles.

The CLI can also be run ad hoc:

bash
npx lumibase --help

Node.js 22+ is required for the CLI; the launcher in packages/cli/bin/lumibase.js refuses older runtimes before loading the ESM graph.

Commands

CommandWhat it does
lumibase init [name]Scaffold a new project
lumibase typesGenerate TypeScript types from a running CMS
lumibase doctorReport resolved configuration and probe connectivity (--security: audit the config against the production checklist)
lumibase skills <list|pull|push|install>Sync Site Skills (agent playbooks) with a site

lumibase help and lumibase version are also accepted, as are --help / -h and --version / -v.

Connection settings

Every command that talks to a CMS resolves three settings with precedence flag > environment > config file:

SettingFlagEnvironmentlumibase.config.json
CMS base URL--urlLUMIBASE_URLurl
Site / tenant id--siteLUMIBASE_SITE_IDsiteId
Bearer token--tokenLUMIBASE_TOKEN—

The token is deliberately not readable from the config file, because that file is meant to be committed. A token key there is rejected with an error rather than silently ignored — see readConfigFile in packages/cli/src/config.ts.

json
{
  "url": "https://api.mysite.lumibase.dev",
  "siteId": "site_abc123",
  "typegen": {
    "out": "src/lumibase-types.d.ts",
    "exclude": ["internal_logs"]
  }
}

The config file is looked up from the working directory upward until the filesystem root, so it resolves from any package inside a monorepo.

Requests are sent with Authorization: Bearer <token> and X-Lumi-Site: <siteId> — the same headers the SDK client uses.

lumibase init

Delegates to create-lumibase, which stays the single implementation of the scaffold so npm create lumibase and lumibase init can never drift. All arguments are forwarded verbatim:

bash
lumibase init my-site --template cloudflare --pm pnpm

Three templates are accepted — nextjs, default, and cloudflare (TEMPLATES in packages/create-lumibase/src/index.ts). Passing no --template leaves the choice to the prompt, where nextjs is preselected: a Next.js website plus the CMS and Studio in Docker, seeded content, and a publishable key. The template named default is the Hono + Drizzle starter, not the default choice. Getting started walks through each one.

The scaffolder is not a dependency of lumibase — it runs once per project, and its prompt/template libraries have no place in every install of a runtime package. resolveScaffoldCommand in packages/cli/src/commands/init.ts fetches it through the one-off runner of the package manager that invoked the CLI (npx --yes / pnpm dlx / yarn dlx / bunx, from npm_config_user_agent; yarn classic falls back to npx), pinned to the CLI's own version (create-lumibase@<version>) so both binaries always come from the same release.

That pin has one consequence worth knowing before it surprises you: init resolves the scaffolder from the registry, not from this repository. A template that exists in the source tree is therefore not reachable through lumibase init until a create-lumibase that contains it has been published at the CLI's version. How that fails depends on the age of the published scaffolder: releases up to 1.0.0-rc.1 do not validate --template, so the command fails inside the scaffolder with a missing-template-directory error; later releases reject the name up front with Unknown template, listing only the templates that release ships. Either way the name is valid — the published artifact simply predates it. npm create lumibase@latest has the same constraint for the same reason. If you are working from a checkout and need a template that is not published yet, run the scaffolder from the repo instead of going through either entry point.

lumibase types

Fetches the collection manifest from GET /api/v1/typegen/schema (served by apps/cms/src/routes/typegen.ts) and renders it with generateTypes from @lumibase/sdk.

bash
lumibase types                                # -> lumibase-types.d.ts
lumibase types --out src/lumibase-types.d.ts  # custom path; directories are created
lumibase types --include articles,authors     # only these collections
lumibase types --exclude internal_logs        # skip these collections
lumibase types --no-branded                   # plain string ids instead of branded ones
lumibase types --import-from @lumibase/sdk    # module the generated file imports from
lumibase types --stdout                       # print instead of writing a file

The generated file imports its helper types (ID, Locale, Brand) from lumibase by default (DEFAULT_IMPORT_FROM in packages/cli/src/commands/types.ts) — the package a project running this command already has installed. A project that depends on the SDK directly can point the import elsewhere with --import-from @lumibase/sdk or typegen.importFrom in lumibase.config.json; the module named must be installed in the project consuming the types.

Deterministic output and --check

The generated header carries no timestamp, host, or site id. Two machines pointed at the same schema produce byte-identical files, which makes the output safe to commit and verify in CI:

yaml
- run: npx lumibase types --check

--check exits non-zero when the file is missing or stale, and never writes anything. Without --check, an unchanged file is left untouched rather than rewritten, so watchers do not rebuild for nothing.

lumibase doctor

Prints what was resolved, where each value came from, and whether the CMS answers:

code
✔ node         v22.22.2
✔ config       /path/to/lumibase.config.json
✔ url          http://localhost:1989 (from lumibase.config.json)
✔ siteId       site_abc123 (from lumibase.config.json)
✔ token        tok_••••••••3f (from environment)
✔ health       reachable — status: healthy
✔ schema       12 collections readable

The health probe calls the unauthenticated /health endpoint (apps/cms/src/routes/health.ts); the schema check exercises the same authenticated request lumibase types makes, so a green doctor means typegen will work. Tokens are masked: a short prefix is kept so an operator can tell which token was picked up without the value reaching CI logs.

doctor exits non-zero if any check fails.

lumibase doctor --security

--security replaces the connectivity checks with an offline audit of the project's configuration. It reads .env, .env.local, .dev.vars, wrangler.toml [vars] and the compose environment: entries. Each finding has a severity (critical, warning, info), the rule it applies and a fix hint. Secret values are never printed.

FlagEffect
--productionApply the production checklist even when NODE_ENV / LUMIBASE_ENV is not production
--env-file <a,b>Read these dotenv files instead of the defaults
--jsonPrint the report as JSON (ok, mode, runtime, sources, summary, findings)

The command exits 1 when any finding is critical. A fresh create-lumibase scaffold passes with zero critical findings. For the full rule list, see Secure defaults.

lumibase skills

Syncs Site Skills — Markdown playbooks for the site's agents — between a directory in your repository and a site. The CLI only moves files: the CMS parses and validates each document, so the format has one implementation.

CommandWhat it does
lumibase skills listTable of the site's skills. --status <s> filters; --json prints the raw rows.
lumibase skills pullWrites every skill to <dir>/<slug>.skill.md. --dir (default skills), --status.
lumibase skills pushCreates or updates skills from the *.md files in <dir> (README.md is skipped), including skills that are already active. --activate, --dry-run, --check.
lumibase skills install <src>Adds skills from a directory, a single .md file, or an npm package that is already installed locally. Never changes a skill that is already active. --activate, --dry-run.
bash
lumibase skills pull
lumibase skills push --dry-run
lumibase skills push --check      # CI: exit 1 if the site differs from the directory
lumibase skills install @acme/lumibase-skills
  • New skills land as drafts. Pass --activate to activate them; otherwise review and activate in Studio (Mission Control → Skills). Existing skills keep their status.
  • push deploys; install does not touch live skills. push treats the directory as the source of truth and sends updateActive: true, so pushing an edit to an active skill changes agent behaviour immediately. install does not: a file that would change an active skill is reported as ACTIVE_SKILL_CHANGE and the live skill is left as it was — review it in Studio, or deploy it with push.
  • Idempotent. A file whose content matches the stored version is reported unchanged and writes nothing.
  • Exit codes. push and install exit 1 when any document is rejected; the other documents are still applied. --check also exits 1 when anything would be created or updated.
  • install downloads nothing. A path that exists wins; otherwise the name is resolved under node_modules, walking up from the working directory. Inside a package the skills directory is package.json → lumibase.skills, or skills/ when that key is absent. The package name and version are recorded as the version's source — a label the CLI declares; the server-recorded author is the authoritative "who".
  • One direction. push never deletes: a skill that exists on the site but not in the directory is left alone, and --check does not report it.
  • Token. The endpoints are under /api/v1/agent, and every skill read and write needs a control-plane admin, so the token needs admin access to the site. Non-admin skill authors are not supported.
Last modified: 15/11/2026