CLI

Scaffold a Celestia web monorepo or native desktop (GPUI) app with npx @celestia-project/create

The @celestia-project/create CLI scaffolds a new project from the template. Pick the web monorepo (Next.js + Hono) or a desktop GPUI app built on celestia-ui.

Quick start

bash
npx @celestia-project/create my-app

The installer asks which template you want (web or desktop). You can also pass it up front:

bash
npx @celestia-project/create my-app --template webnpx @celestia-project/create my-desktop --template desktop

Web template

  1. Ask which features you want (auth, dashboard, blog) — required features are resolved automatically
  2. Clone the template and run pnpm install
  3. Add/remove features through the feature manager (features.json stays in sync)
  4. Write apps/api/.env and apps/web/.env, including a generated BETTER_AUTH_SECRET
  5. Optionally push the database schema (db:push) and initialize git

Desktop template

  1. Clone the template and extract packages/desktop
  2. Keep celestia-ui + the starter app (drops the component gallery)
  3. Rename the app crate to your project name and write a root README.md
  4. Optionally run cargo check and initialize git

Then:

bash
cd my-desktopcargo run -p my-desktop

See Desktop (GPUI) for the component library and bootstrap notes, and Desktop Components for Toggle / Item / Menubar and the app composites.

Non-interactive usage

bash
npx @celestia-project/create my-app --template web --features auth,dashboardnpx @celestia-project/create my-desktop --template desktop
FlagDescription
-t, --template <name>web or desktop. Default: prompt; web when non-interactive.
--features <a,b>Web only — features to install. Dependencies (requires) are added automatically.
--repo <url|path>Template repository to clone. Also accepts a local git path for testing.
-h, --helpShow help.

Requirements

  • Node.js ≥ 20 and git on your PATH
  • Web: pnpm; a running PostgreSQL if you let the installer push the schema
  • Desktop: Rust ≥ 1.97 (cargo) to build and run

Database migration errors

If db:push fails during scaffolding (e.g. PostgreSQL isn't running yet), the CLI will show the exact commands to recover:

bash
# Once your database is up:cd my-apppnpm --filter @workspace/db db:push
# Or with a one-liner:DATABASE_URL="postgresql://..." pnpm --filter @workspace/db db:push

Need a local database? Start one with Docker:

bash
docker run -d --name celestia-db \  -e POSTGRES_USER=postgres \  -e POSTGRES_PASSWORD=postgres \  -e POSTGRES_DB=celestia \  -p 5432:5432 postgres:16-alpine

Testing the CLI locally

bash
# Fastest — run directly with node (from the monorepo root)node packages/cli/src/index.js my-test-app
# Simulate the installed bin via npm linkcd packages/cli && npm linkcreate-celestia my-test-app
# Most realistic — pack a real .tgz and run it via npxcd packages/cli && npm packnpx ./celestia-project-create-*.tgz my-test-app

Or use the npm scripts from packages/cli:

bash
pnpm --filter @celestia-project/create test:run   # node directpnpm --filter @celestia-project/create test:pack  # tarball → npx

Publishing

The CLI is published to npm under the @celestia-project org using the monorepo publish script:

bash
# Dry run — previews what will be uploadedpnpm publish:dry-run
# Publish all packages (@celestia-project/ui + @celestia-project/create)pnpm publish:packages

DEFAULT_REPO in packages/cli/src/index.js points at the public template repository — update it if you fork. To try the CLI from this repository without publishing, run pnpm scaffold.

NextPackages