Setup Wizard

Production-grade interactive CLI for configuring a Vibe44 checkout in minutes.

The Setup Wizard is a powerful, interactive terminal utility designed to configure your entire Vibe44 project stack in under 10 minutes. It automates collecting project metadata, selecting infrastructure providers, validating API keys, generating application secrets, setting up .env.local, and managing initial database deployments with a resumable, stateful flow.

Quick Start

From the root of your downloaded Vibe44 repository, run the following command:

npm run setup-wizard

The root script invokes the launcher (packages/setup-wizard/launcher.mjs), which manages dependency checks, package compilation, and child process execution safely across multiple shells (including Bash, zsh, Windows PowerShell, and cmd.exe).

Import Existing Environment Keys

To seed the wizard with credentials from an existing production or staging environment file, pass the --from-env flag:

npm run setup-wizard -- --from-env .env.production

Non-Interactive Setup (CI/CD / Rapid Dev)

To skip prompts entirely, accept all defaults, and force merge or overwrite configuration:

npm run setup-wizard -- --yes --overwrite --skip-install

CLI Flags

Customize your setup run using standard command-line flags. Note that when running via npm scripts, pass options after the -- separator.

Execution Flow

When you launch npm run setup-wizard, the CLI entrypoint (src/index.ts) executes the setup sequence in a robust, structured order:

graph TD
    A[Launch CLI] --> B[Run Preflight Checks]
    B --> C{Check for Resume State?}
    C -- Yes --> D[Load Checkpoint]
    C -- No --> E[Interactive Prompts Clack]
    D --> F[Merge Env Key Imports]
    E --> F
    F --> G[Generate CSRF & Auth Secrets]
    G --> H{Dry Run?}
    H -- Yes --> I[Print Plan & Exit]
    H -- No --> J[Resolve .env.local Conflicts]
    J --> K[Write .env.local]
    K --> L[Post-Setup: npm install & Supabase db push]
    L --> M[Clear Checkpoint & Complete]

1. Preflight Checks

Verifies that:

• The project directory exists and has active read/write permissions.
• The Node.js version is >= 20.
• The package manager (npm, pnpm, yarn, bun) is successfully detected.
• Any potential .env.local conflict is flagged.

2. State & Resume Resolution

• Reads the unique workspace hash to look for any existing checkpoint file under ~/.vibe44/setup-wizard/{projectHash}.json (or your custom SETUP_WIZARD_STATE_DIR).
• Prompts to resume where you left off if a step failed previously or if you exited early.

3. Collection (Interactive / Automatic)

• Interactive Mode: Starts a custom @clack/prompts run split into logical groups:
  1. Project Identity (Name, display name, support email).
  2. Infrastructure (Payment, AI, Voice, Email, Analytics, Jobs, Sentry).
  3. API Keys (Dynamic inputs based on your chosen providers).
• Non-Interactive Mode (--yes): Bypasses prompts and uses smart system defaults.

4. Code & Secret Generation

• Generates high-entropy cryptographic strings for CSRF_SECRET and NEXT_AUTH_SECRET if they are not already set.
• Automatically handles validation checks on provider keys (e.g., verifying that Stripe secret keys start with sk_).

5. File Resolution & Write Plan

• Evaluates existing configuration files.
• If .env.local is present, it prompts to Merge, Backup & Overwrite, Overwrite, or Abort to keep your historical variables safe.

6. Post-Setup Actions

• Installs dependencies using your detected package manager.
• Installs the Supabase CLI, verifies database status, and pushes Drizzle schema changes automatically unless explicitly skipped.

Security & Invariants

To keep your credentials secure, the wizard enforces strict operational standards:

• No Sensitive Checkpoints: API keys are never persisted to local checkpoint files. Checkpoints only save project identity and infrastructure choices. If you resume a checkpoint, you will only be asked to provide your keys.
• Dry-Run Redaction: --dry-run automatically masks all secret values in terminal logs unless you explicitly pass --show-secrets.
• Safe Database Mutators: Supabase db pushes run a dry-run check first (supabase db push --dry-run) to guarantee schema validity before performing mutations.

️ Recovery & Troubleshooting

If a post-setup step (such as npm install or database migration) fails, the wizard saves a recovery checkpoint. You do not need to re-enter your answers:

1. Resolve the reported issue (e.g., check network connectivity or database keys).
2. Run the wizard with the resume flag:

   npm run setup-wizard -- --resume

3. To discard a broken session and start completely fresh:

   npm run setup-wizard -- --reset

Source Directory Map

For core developers looking to customize or maintain the wizard code, the package structure is organized as follows:

packages/setup-wizard/src/
├── index.ts           # CLI orchestration & Commander CLI definition
├── prompts.ts         # Clack interactive prompt layouts and group flows
├── preflight.ts       # Environment, Node version, and directory readiness checks
├── state-machine.ts   # Phase state-machine and dynamic result recording
├── state.ts           # Project-scoped local checkpoint persistence
├── secrets.ts         # Entropy generators and log-redaction helpers
├── generator.ts       # Environment file planning, merging, and writing
├── installer.ts       # Async child process runner for npm install and Supabase CLI
├── exec.ts            # Execa-wrapped async command executors
└── package-manager.ts # Auto-detecting and mapping package manager commands

Copyright © 2026 Scale with Alap. All rights reserved. Built with ❤️ by Scale with Alap.