Onboarding

onboard is the post-install setup step. It fills in your .env, starts the local infrastructure, runs database migrations, and hands you the start command. Run it after create, compose, or template, or any time you want to re-check your environment.

Usage

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. Docker services - if Docker isn't already running, it offers to start Postgres, Valkey, and RustFS from apps/backend.
  3. Migrations - once Postgres is healthy, it runs prisma migrate deploy, but only if migrations aren't already applied. Re-running onboard won't re-prompt or re-migrate a database that's already set up.
  4. 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

FlagWhat it does
-y, --yesSkip prompts and accept defaults. .env is still created.
--skip-migrationsSkip Docker services and database migrations. Env setup only.
--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, starts Docker, and applies migrations:

npx @hype-stack/cli onboard --yes

If your CI starts its own infrastructure, skip the Docker and migration steps and handle them yourself:

npx @hype-stack/cli onboard --yes --skip-migrations

When to re-run

onboard is idempotent and safe to run again. Existing .env values are kept, already-applied migrations are detected and skipped, and Docker is only started if it's down. Run it after adding new packs, pulling a fresh checkout, or switching starter variants.