Source: https://www.hype-stack.dev/docs/cli

# Create a Project

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

## CLI map

| Command     | Docs                                                        | Job                                              |
| ----------- | ----------------------------------------------------------- | ------------------------------------------------ |
| `create`    | This page                                                   | Scaffold the bare template                       |
| `compose`   | [Compose Your Stack](/docs/cli/add-pack)                    | Install packs into a project                     |
| `template`  | [Add a Template](/docs/cli/add-template)                    | Install a curated pack bundle                    |
| `onboard`   | [Onboarding](/docs/cli/onboard)                             | Fill `.env` from installed packs                 |
| `deploy`    | [Deploy](/docs/cli/deploy)                                  | Ship the web stack, mobile app, and extension    |
| `mcp`       | [MCP Server](/docs/cli/mcp)                                 | Expose CLI tools to AI agents                    |
| `community` | [Build your own pack](/docs/packs-templates/build-your-own) | Build and install packs from outside the catalog |

**You may not need this command**

If your next step is [`compose`](/docs/cli/add-pack) or [`template`](/docs/cli/add-template), you can skip `create`. Run
either without a project and it runs the same scaffolding wizard for you first, then installs your packs. Reach for
`create` on its own only when you want the bare template with nothing added yet.

## Usage

```bash
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`](/docs/cli/add-template) and [`compose`](/docs/cli/add-pack) commands, then run
[`onboard`](/docs/cli/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](/docs/cli/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](https://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.

| Skill                           | Source                                                                                                 | What it teaches the agent                             |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `find-skills`                   | [vercel-labs/skills](https://www.skills.sh/vercel-labs/skills/find-skills)                             | Look for a skill before improvising a workflow        |
| `frontend-design`               | [anthropics/skills](https://www.skills.sh/anthropics/skills/frontend-design)                           | Distinctive UI instead of generic AI-looking pages    |
| `web-design-guidelines`         | [vercel-labs/agent-skills](https://www.skills.sh/vercel-labs/agent-skills/web-design-guidelines)       | Accessibility, focus states, layout rules             |
| `vercel-react-best-practices`   | [vercel-labs/agent-skills](https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices) | React and rendering performance patterns              |
| `grill-with-docs`               | [mattpocock/skills](https://www.skills.sh/mattpocock/skills/grill-with-docs)                           | Interrogate a plan against the docs before building   |
| `improve-codebase-architecture` | [mattpocock/skills](https://www.skills.sh/mattpocock/skills/improve-codebase-architecture)             | Find seams and refactor toward them                   |
| `teach`                         | [mattpocock/skills](https://www.skills.sh/mattpocock/skills/teach)                                     | Explain a change instead of just landing it           |
| `landing-page-design`           | [skills-101/superpowers](https://www.skills.sh/skills-101/superpowers/landing-page-design)             | Hero, above-the-fold, and CTA rules for landing pages |
| `better-ui`                     | [jakubkrehel/skills](https://www.skills.sh/jakubkrehel/skills/better-ui)                               | Border radius, optical alignment, hit areas           |
| `emil-design-eng`               | [emilkowalski/skills](https://www.skills.sh/emilkowalski/skills/emil-design-eng)                       | Animation and component polish decisions              |
| `no-ai-slop`                    | [petergyang/no-ai-slop](https://www.skills.sh/petergyang/no-ai-slop/no-ai-slop)                        | Edit copy so it stops reading like AI wrote it        |

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:

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

| Flag                         | What it does                                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| `-t, --theme <theme>`        | Frontend color theme.                                                                                |
| `--admin-theme <theme>`      | Admin color theme. Defaults to `--theme`.                                                            |
| `--mobile-theme <theme>`     | Mobile app color theme. Defaults to `--theme`.                                                       |
| `--extension-theme <theme>`  | Browser extension color theme. Defaults to `--theme`.                                                |
| `--radius <value>`           | Frontend corner radius as a CSS length: `0rem`, `0.375rem`, `0.625rem`, `0.75rem`, `1rem`, `1.4rem`. |
| `--admin-radius <value>`     | Admin corner radius. Defaults to `--radius`.                                                         |
| `--mobile-radius <value>`    | Mobile app corner radius. Defaults to `--radius`.                                                    |
| `--extension-radius <value>` | Browser extension corner radius. Defaults to `--radius`.                                             |
| `--mode <light\|dark>`       | Color mode the app boots in.                                                                         |
| `-n, --name <name>`          | Project name. Same as the positional argument.                                                       |
| `-d, --directory <path>`     | Exact directory to scaffold into. Without it the project lands in a folder named after it.           |
| `-e, --editor <editors>`     | AI editors to ship rules for, comma-separated or repeated.                                           |
| `--no-skills`                | Skip the agent skills install from skills.sh.                                                        |
| `--no-setup`                 | Skip the Docker and migrations step. Useful in CI or when you bring your own database.               |
| `--no-install`               | Skip `pnpm install`. Implies `--no-setup`, since migrations need the toolchain.                      |
| `-y, --yes`                  | Skip confirmations. Needs a name, and answers yes to Docker and migrations.                          |

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`](/docs/cli/add-pack) and [`template`](/docs/cli/add-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:

```json
{
  "$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:

```bash
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](/docs/getting-started/fastest-template) for the full first-run walkthrough.