@clearcms/admin

The editor for clear — a portable, files-first headless CMS. One process per site; reads and writes a single bucket and its derived index. MIT.

Install

For a brand-new project, use the scaffolder — it sets up the bucket, the index, and a working Astro frontend in one step:

npx @clearcms/create my-site
cd my-site
pnpm install
pnpm dev

To bring @clearcms/admin into a project you already have:

npm install @clearcms/admin
npx clear-admin bootstrap   # creates ./data/storage + ./data/clear.db, seeds owner
npx clear-admin start       # admin UI on http://localhost:3001

The first run prints an owner password — save it.

CLI

clear-admin start                       boot admin (auto-bootstrap on first run)
clear-admin bootstrap                   migrate + seed (idempotent)
clear-admin migrate                     apply DB migrations only
clear-admin import <dir>                import a directory of markdown files
clear-admin import <dir> \              import an Astro Content Collections project
  --from-astro-config=<path>
clear-admin scaffold --from=<spec.json> provision schema + seeds
clear-admin reindex                     rebuild the libSQL index from the bucket
clear-admin sync-media [--backfill]     register raw media drops in the index
clear-admin reset-password <email>      reset owner password
clear-admin help                        full help

Environment

CLEAR_STORAGE_ROOT   bucket directory                (default ./data/storage)
CLEAR_DB_URL         libSQL connection url           (default file:./data/clear.db)
PORT                 admin HTTP port                 (default 3001)
HOST                 admin HTTP host                 (default 127.0.0.1)
CLEAR_OWNER_EMAIL    seed-time owner email           (default [email protected])
CLEAR_OWNER_PASSWORD seed-time owner password        (default: random, printed once)

Where the data lives

my-site/data/storage/   ← bucket. Yours. Portable. Gitable. The source of truth.
my-site/data/clear.db   ← derived index + operational state (sessions, tokens, jobs).
                          The projection is rebuildable via `clear-admin reindex`;
                          operational state is the DB's own source of truth.

A frontend reads the bucket directly via @clearcms/sdk (fs, r2, s3 backends) — it never touches the admin or the database. See @clearcms/astro for the Astro Content Layer adapter.

Documentation

• Source + ADRs: https://github.com/clearcms/clear-headless
• Domain language: CONTEXT.md
• Bucket layout + REST contract: docs/CONTENT-PROTOCOL.md
• Known issues for this release: docs/known-issues.md

Status

Pre-1.0. The shipped surface is production-shaped but expect rough edges; see docs/known-issues.md for what's known about the current release.

License

MIT.