Create a Project

The Hype CLI scaffolds a new Hype Stack project with one command.

CLI map

Usage

npx @hype-stack/cli create my-app

Before anything else, create checks the machine: Node 20 or newer and pnpm 12 or newer are required, Docker is recommended. A missing requirement stops the run with the fix printed.

Then it walks you through a few prompts. Anything you already answered with a flag is skipped:

1. Project name and directory - where to scaffold it. The name can be the first argument or --name
2. AI editors - cursor, t3code, claude, codex, copilot, opencode, windsurf (tick every one your team uses)
3. Frontend look - a color theme and how round the corners should be
4. Admin, mobile, and extension look - one question each, "copy the frontend settings?", answered yes by default
5. Docker and migrations - after the scaffold, whether to start the databases and create the tables now

create clones the base template, the empty canvas. It does not pick a starter or install feature packs. Add those after with the template and compose commands, then run onboard to fill in your .env (both commands offer it at the end of a run).

What a run does

1. Resolves the template release to clone. HYPE_STACK_TEMPLATE_REF overrides it with a tag, branch, or commit.
2. Clones it, strips the template's git history, and renames the @hype-stack/* workspace scope to your project name.
3. Writes the editor rules you picked and, where the editor supports a project-scoped config, an MCP entry so the project opens with the tools attached.
4. Writes stack.json with the apps it found, their paths, and a base install record carrying the template commit.
5. Applies your theme, radius, and color mode to every app.
6. Installs the agent skills (below).
7. Runs pnpm install. If your pnpm is too old to run the pinned version, the install is retried through npx pnpm@12 and the CLI prints the permanent fix.
8. Runs git init and makes the first commit.
9. Copies every .env.example to .env.
10. Offers to start Docker in apps/backend (remapping busy ports), waits for Postgres, runs prisma migrate dev, and mirrors the schema into the test database.

Agent skills

Right after the scaffold, create pulls a starter set of agent skills from skills.sh through npx skills add. They are fetched fresh on every run rather than vendored in the template, so a new project gets the current text of each skill, not whatever was true at the template's last release. The skills CLI records what it installed in skills-lock.json, so npx skills update can move them forward later.

Skills land in .agents/skills, the shared location Cursor, Codex, Copilot, OpenCode, and Cascade read directly. Claude Code gets a .claude/skills link to the same folder. Which agents are named follows the editors you picked, so a --editor cursor,claude project is wired for both.

A source that cannot be reached does not fail the scaffold. create prints the installer's output and the exact npx skills add command to retry it, then carries on. Pass --no-skills to skip the step entirely, for example in CI or on a machine without network access to GitHub.

Theming every app

The project ships four themable surfaces: the customer-facing frontend, the internal admin dashboard, the Expo mobile app, and the browser extension. Each carries its own theme and corner radius. The frontend section asks for both values. Then admin, mobile, and extension each open with "copy the frontend settings?", which is what most people want, so accepting all three is three keypresses. Say no to any of them and you get that app's own theme and radius pickers. Sections only appear for apps your project has.

Themes are color only and radius is shape only, so switching palette never reshapes your buttons and cards. The same theme catalog drives every app, the desktop build included since it ships the frontend's stylesheet; the CLI converts the tokens to the format each app uses (the mobile app's NativeWind stylesheet takes HSL channels, the others take OKLCH).

Every answer has a flag, which is how the preview site's copy-command button reproduces what you saw on screen:

npx @hype-stack/cli create my-app --theme ocean --radius 0.75rem --admin-theme midnight --mode dark

A flag skips its question. Anything you leave out is still prompted for, so you can pin just the theme and pick the rest interactively. The same flags work on compose and template.

What gets scaffolded

After the CLI finishes, you get:

my-app/
  apps/
    backend/     # Hono API with Prisma, Kysely
    frontend/    # React SPA with TanStack Router, Tailwind
    mobile/      # Expo app with expo-router, NativeWind
    extension/   # Browser extension with Vite, Tailwind
  packages/      # Shared types, utils, configs
  docker-compose.yml
  nx.json
  pnpm-workspace.yaml
  stack.json

The stack.json file tracks the project's apps, their paths, and installed packs. Every pack, template, and the base template itself gets an install record with the commit it came from, which is how a later run can tell what moved:

{
  "$schema": "https://www.hype-stack.dev/schema/stack.json",
  "version": 1,
  "name": "my-app",
  "apps": { "backend": "apps/backend", "frontend": "apps/frontend", "admin": "apps/admin" },
  "packages": { "enums": "packages/enums" },
  "installedPacks": [],
  "installs": [{ "kind": "base", "id": "BetterTyped/hype-stack", "commit": "d6eb1559" }]
}

After scaffolding

Install dependencies and start the stack:

cd my-app
pnpm dev

If you opted into Docker services and migrations during create, Postgres, Valkey, and RustFS are already running. If not, start them with docker compose up -d from apps/backend, then create the tables with pnpm --filter @hype-stack/backend migration:create.

See Fastest Template for the full first-run walkthrough.