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

# Onboarding

`onboard` is the env setup step. It fills in your `.env` and hands you the start command. `compose` and `template` offer
to run it for you at the end of an install, and you can run it directly any time you want to re-check your environment.

Docker and database migrations are not part of `onboard`: `create`, `compose`, and `template` handle those during the
install itself.

## Usage

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

Run it from your project root (the folder with `stack.json`), or point it elsewhere with `--cwd`.

## What it does

1. **Env setup** - walks every `.env.example` in the project and prompts for any variable that's empty or still a
   placeholder. Values are written into the matching `.env` file.
2. **Pack tips** - prints setup tips from the packs you installed.
3. **Start command** - prints `pnpm dev` so you know where to go next.

## Env prompting

`onboard` only asks for env sections that belong to packs you actually installed. It reads `stack.json`, which records
the onboarding sections each installed pack declares, and prompts for those plus the base template sections (Config,
Databases, Sentry, Resend).

This matters when you switch variants. If you started on the WorkOS starter and later moved to Better Auth, the
append-only install leaves an old `# Workos` section in `.env.example`. `onboard` skips it instead of asking for WorkOS
keys you no longer need, and shows a `skipped (pack not installed)` note so the skip is visible.

Sections from the base template always prompt. Press Enter on any prompt to leave it blank and move on.

## Flags

| Flag           | What it does                                               |
| -------------- | ---------------------------------------------------------- |
| `-y, --yes`    | Skip prompts and accept defaults. `.env` is still created. |
| `--cwd <path>` | Run against a different working directory.                 |

## In CI

For a non-interactive run, use `--yes`. It creates `.env` from `.env.example` without prompting:

```bash
npx @hype-stack/cli onboard --yes
```

## When to re-run

`onboard` is idempotent and safe to run again. Existing `.env` values are kept: press Enter on any prompt to leave the
current value alone. Run it after adding new packs, pulling a fresh checkout, or switching starter variants.