CLI Reference

Complete reference for the create-starterbase-app CLI tool.

Installation

The CLI is available via npm:

# Run directly with npx (recommended)
npx create-starterbase-app <command>

# Or install globally
npm install -g create-starterbase-app
starterbase <command>

Commands

Create a New Project

npx create-starterbase-app <project-name> [options]

Or use the explicit new subcommand:

npx create-starterbase-app new <project-name> [options]

Options

Option Alias Description Default
--database <type> -d Database type: sqlite or postgresql Prompts user
--yes -y Non-interactive mode with defaults, auto-starts Docker false
--skip-install Skip dependency installation (npm/uv) false
--no-start Don't auto-start Docker Compose after creation Starts by default

Examples

# One-command setup (recommended) - creates and starts everything
npx create-starterbase-app my-app -y

# Interactive mode (prompts for options)
npx create-starterbase-app my-app

# Specific database
npx create-starterbase-app my-app --database sqlite
npx create-starterbase-app my-app -d postgresql -y

# Development modes
npx create-starterbase-app my-app -d sqlite -y --no-start
npx create-starterbase-app my-app -d postgresql --skip-install

Database Options

Option Connection URL Best For
sqlite sqlite+aiosqlite:///./starterbase.db Local development, learning, prototypes
postgresql postgresql+asyncpg://user:pass@host/db Production, Docker, teams

License Management

Starterbase requires a valid license to create projects.

Activate License

npx create-starterbase-app activate <license-key>

Validates your license key and stores it locally. You'll receive a license key via email after purchase.

Output:

Validating license key...

✓ License activated successfully!

Licensed to: your@email.com

Check License Status

npx create-starterbase-app status

Shows your current license status.

Output:

✓ License Active

Details:
  Email: your@email.com
  Activated: 1/7/2026
  Last Checked: 1/7/2026

Deactivate License

npx create-starterbase-app deactivate

Removes the stored license from your machine. Use this when transferring your license to another computer.

How It Works

Project Creation Flow

  1. License Check: Verifies your license is valid (re-validates every 7 days)
  2. Project Setup: Copies the template to your target directory
  3. Configuration: Prompts for database choice (unless using -y or -d)
  4. Environment Files: Creates .env files with appropriate configuration
  5. Dependencies: Runs npm install and uv sync (unless --skip-install)
  6. Docker: Starts docker compose up (unless --no-start)

License Storage

Licenses are stored locally at:

Platform Location
macOS/Linux ~/.starterbase/license.json
Windows %USERPROFILE%\.starterbase\license.json

Offline Support

If the license server is unreachable, previously validated licenses continue to work. The CLI checks the last validation timestamp and allows offline usage within a reasonable grace period.

Troubleshooting

"No license key found"

You haven't activated a license yet:

npx create-starterbase-app activate <your-license-key>

"Invalid or revoked license key"

Your license key may be:

"Could not validate license key"

The license server is unreachable. Check:

Docker Issues

If Docker Compose fails to start:

# Check Docker is running
docker info

# Start manually
cd my-app
docker compose up

Need Help?