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

# Add a Template

Templates are curated project starters: a starter, a layout, and a set of feature packs pre-wired together, plus a
custom theme and extra pages. The `template` command installs one into a Hype Stack project, and scaffolds the project
first when you run it in an empty directory.

## Usage

Install a template by id:

```bash
npx @hype-stack/cli template better-studio
```

Omit the id to pick interactively:

```bash
npx @hype-stack/cli template
```

If there is no project in the current directory, the [`create`](/docs/cli) wizard runs first, preseeded with the
template's theme, radius, and color mode. Then the command expands the template into one variant per slot (starter,
layout, billing provider) plus its fixed feature packs, installs them like a normal compose, and layers the template's
frontend overrides (landing page, custom theme, re-skinned auth screens, and so on) on top so the template owns those
paths. Docker and migrations run at the very end, once, after every pack is in.

**Use the wizard**

You rarely need to hand-build the full command. Run `npx @hype-stack/cli template` with no flags and the wizard walks
you through picking a template, swapping slot variants, and handling licenses. Reach for the flags below only in CI or
scripts where prompts aren't an option.

### Swapping slot variants

A template names a pack family for each slot rather than a concrete pack, so you can swap variants at install time.
Every family the template ships is a slot: the auth starter, the layout, and the billing provider. Pick interactively,
or preselect with `--variants`:

```bash
npx @hype-stack/cli template better-studio --variants starter-saas=starter-saas-workos,layout=layout-basic,pack-billing=pack-billing-polar
```

A template license covers every variant of each slot, so swapping never costs extra. A family the template has no slot
for, or a pack from a different family, aborts before anything is written and lists the real options.

### Adding extra packs

Add feature packs that fall outside the template's own scope with `--packs`:

```bash
npx @hype-stack/cli template better-studio --packs pack-notifications,pack-projects
```

### Overriding the template's look

Every template ships a canonical theme, corner radius, and color mode. Those preselect the pickers during install, and
these flags override them outright, which is how the preview site's copy-command button reproduces the combination you
were looking at:

```bash
npx @hype-stack/cli template better-studio --packs pack-teams --theme ocean --radius 1rem --mode dark
```

The admin app, mobile app, and browser extension all follow the frontend unless you say otherwise with their own flags
(`--admin-theme`, `--mobile-theme`, `--extension-theme`, and the matching `-radius` flags).

### Flags

| Flag                           | What it does                                                          |
| ------------------------------ | --------------------------------------------------------------------- |
| `[id]`                         | Template id. Omit to choose from a list.                              |
| `--variants <family=pack,...>` | Preselect slot variants instead of prompting.                         |
| `--packs <a,b,c>`              | Extra feature packs to add on top of the template.                    |
| `-t, --theme <theme>`          | Frontend color theme, overriding the template's.                      |
| `--admin-theme <theme>`        | Admin color theme. Defaults to `--theme`.                             |
| `--mobile-theme <theme>`       | Mobile app color theme. Defaults to `--theme`.                        |
| `--extension-theme <theme>`    | Extension color theme. Defaults to `--theme`.                         |
| `--radius <value>`             | Frontend corner radius as a CSS length, e.g. `1rem`.                  |
| `--admin-radius <value>`       | Admin corner radius. Defaults to `--radius`.                          |
| `--mobile-radius <value>`      | Mobile app corner radius. Defaults to `--radius`.                     |
| `--extension-radius <value>`   | Extension corner radius. Defaults to `--radius`.                      |
| `--mode <light\|dark>`         | Color mode the app boots in, overriding the template's `defaultMode`. |
| `--force`                      | Overwrite existing files.                                             |
| `-y, --yes`                    | Skip confirmation prompts (requires an id).                           |
| `--cwd <path>`                 | Run against a different working directory.                            |

### Running in CI

There is no credential flag. Create an API key on the [API keys](/api-keys) page and pass it as an env var:

```bash
HYPE_STACK_TOKEN=hsk_ci_xxx npx @hype-stack/cli template better-studio --yes
```

`HYPE_STACK_TOKEN` takes priority over whatever `npx @hype-stack/cli login` stored locally, so the same command works on
your machine and on a runner.

## Available templates

Every template takes a starter slot and a layout slot. The table shows the default variants and the packs that are
fixed.

| Template                                                         | Fixed packs                              | Default layout  | Look           |
| ---------------------------------------------------------------- | ---------------------------------------- | --------------- | -------------- |
| [`better-studio`](/docs/packs-templates/templates/better-studio) | `pack-billing-stripe`                    | `layout-glass`  | ocean, dark    |
| [`open-calendar`](/docs/packs-templates/templates/open-calendar) | `pack-billing-stripe`, `pack-calendar`   | `layout-glass`  | lime, light    |
| [`aether`](/docs/packs-templates/templates/aether)               | `pack-billing-stripe`, `pack-ai-chat`    | `layout-glass`  | default, dark  |
| [`vault`](/docs/packs-templates/templates/vault)                 | `pack-billing-stripe`                    | `layout-basic`  | black, dark    |
| [`mind-map`](/docs/packs-templates/templates/mind-map)           | `pack-billing-stripe`, `pack-whiteboard` | `layout-joyful` | paper, light   |
| [`indie-hacker`](/docs/packs-templates/templates/indie-hacker)   | `pack-newsletter`                        | `layout-basic`  | crimson, light |

Billing is a slot too: a pack from a family (Stripe here) is swappable for its siblings, so any of these can run on
Lemon Squeezy or Polar instead.

A template license covers every variant of every slot plus the fixed packs. The third-party accounts behind them
(WorkOS, Stripe, Resend, an AI provider) are yours to create; each template page lists which ones it needs.

## After install

The template and its packs are recorded in `stack.json`, the template as its own install record:

```json
{
  "installedPacks": ["starter-saas-betterauth", "layout-glass", "pack-billing-stripe"],
  "installs": [
    { "kind": "base", "id": "BetterTyped/hype-stack", "commit": "d6eb1559" },
    { "kind": "pack", "id": "starter-saas-betterauth", "version": "1.0.0", "commit": "3f2a91c0" },
    { "kind": "template", "id": "better-studio", "version": "1.0.0", "commit": "3f2a91c0" }
  ]
}
```

Templates are starting points, not constraints. Once installed, you own all the code. Modify routes, swap providers,
restructure the layout. Nothing is locked.

The template's copy lands in `messages/en.json` on top of what its packs contributed, so the app name and any wording
the template rephrases win. Adding a language is the same as for a plain pack install: see
[Translations](/docs/cli/add-pack#translations).

Add more packs on top at any time:

```bash
npx @hype-stack/cli compose
```

At the end of a `template` or `compose` run the CLI offers to walk you through [`onboard`](/docs/cli/onboard), which
fills in any new env vars the template and its packs need. You can also run it yourself later.