Interactive Setup

The m3-forge init command provides an interactive setup wizard to configure your M3 Forge environment. It generates a .env file with all required configuration values.

Quick Start

# Interactive mode - step through each configuration section
m3-forge init --interactive
 
# Quick mode - generate .env with all defaults
m3-forge init --defaults

Command Options

Setup Modes

Interactive Mode

Step through each configuration section with the ability to:

• Accept default values
• Modify individual settings
• Skip optional sections (OAuth, SMTP, etc.)

m3-forge init --interactive

Quick Mode

Generate a .env file immediately using all default values. JWT secrets are automatically generated.

m3-forge init --defaults

Custom Configuration

Load defaults from a custom YAML file:

m3-forge init --interactive --config ./my-config.yaml

Existing .env Protection

The setup wizard protects existing .env files from accidental overwrites:

Configuration Groups

The setup wizard configures the following sections:

Auto-Generated Values

The following values are automatically generated if left empty:

• JWT_ACCESS_SECRET - 64-byte hex string
• JWT_REFRESH_SECRET - 64-byte hex string

Derived Values

Some values are automatically derived from others:

• GITHUB_CALLBACK_URL - Derived from API_URL + /api/auth/github/callback
• GOOGLE_CALLBACK_URL - Derived from API_URL + /api/auth/google/callback

YAML Configuration Files

Default Template

The setup uses a built-in template (setup-defaults.yaml) containing all default values and configuration metadata.

User Overrides

Create a setup-overrides.yaml file to customize defaults for your environment:

# setup-overrides.yaml
version: "1.0"
 
groups:
  database:
    variables:
      DATABASE_URL:
        default: "postgresql://prod_user:secret@db.example.com:5432/marie_prod"
 
  api_server:
    variables:
      NODE_ENV:
        default: "production"
      FRONTEND_URL:
        default: "https://app.example.com"
      API_URL:
        default: "https://app.example.com"

Override File Locations

The setup wizard searches for override files in this order:

1. --config <path> (CLI argument)
2. ./setup-overrides.yaml (current directory)
3. ~/.m3-forge/setup.yaml (home directory)

Extending Base Configuration

Override files can extend other files:

# production.yaml
extends: "./base-config.yaml"
 
groups:
  # Only override what's different
  database:
    variables:
      DATABASE_URL:
        default: "postgresql://localhost:5432/marie_dev"

Examples

# Quick setup for local development
m3-forge init --defaults

# Interactive setup with custom production defaults
m3-forge init --interactive --config ./production-defaults.yaml

# Non-interactive with force overwrite
m3-forge init --defaults --force

Save Configuration for Team

After interactive setup, you can save your choices:

? Also save as setup-overrides.yaml for future use? Yes

This creates a setup-overrides.yaml that can be committed to your repository (excluding sensitive values like secrets).

Generated .env Format

The generated .env file includes:

• Section headers with descriptions
• Comments explaining each variable
• Timestamp of generation

# .env
# M3 Forge - Environment Configuration
# Generated by m3-forge init
# Generated at: 2025-01-15T10:30:00.000Z
 
# =============================================================================
# Database
# PostgreSQL connection settings
# =============================================================================
# PostgreSQL connection string
DATABASE_URL=postgresql://user:password@localhost:5432/marie_studio
 
# =============================================================================
# JWT Configuration
# JSON Web Token settings for authentication
# =============================================================================
# JWT access token secret
JWT_ACCESS_SECRET=07d880031b1a0ee79fd05613c21f2f05...

Troubleshooting

”Setup defaults template not found”

The CLI package may not be properly installed. Try:

cd packages/cli
pnpm build

“.env file already exists”

Use one of these options:

• --force to overwrite (creates backup)
• --interactive to review and confirm
• Manually delete or rename the existing file

Validation Errors

If required values are missing, you’ll see validation errors. You can:

• Continue with incomplete configuration (not recommended)
• Re-run setup and provide the missing values

Next Steps

m3-forge db migrate --deploy

m3-forge start