saas-boilerplate

SaaS Boilerplate CLI

A command-line interface (CLI) tool to quickly scaffold and set up the SaaS Boilerplate project—a modern, multi-tenant SaaS starter kit built with Next.js 15, Igniter.js, Prisma, Better Auth, Stripe, and more. This CLI handles repository cloning, dependency installation, environment configuration, Docker services setup, and database migrations, getting you from zero to a running development environment in minutes.

🚀 Features

• One-Command Setup: Clone the boilerplate, install dependencies, configure .env, start Docker services (Postgres, Redis, MinIO, Mailhog), and run initial DB migrations.
• Flexible Options: Choose GitHub auth (HTTPS/SSH), package manager (Bun, Yarn, pnpm, npm), and branch (default: main).
• Interactive Prompts: Guided setup with Clack prompts for project name, auth, and package manager.
• AI Code Agents: Configure AI assistants (GitHub Copilot, Cursor, Claude Code, etc.) with LIA for SaaS-specific patterns and Igniter.js awareness.
• Error Handling: Clear, stage-specific error messages with troubleshooting tips (e.g., Docker auth issues, git clone failures).
• Post-Setup Guidance: Detailed success message with next steps, commands, and common configs (Stripe, auth providers).
• Cross-Platform: Supports macOS, Windows, Linux with utils for path normalization and shell ops.
• Dev Mode Support: Optional dev command to restart services and run the development server.

The underlying boilerplate includes:

• Next.js 15 App Router with Shadcn UI/Tailwind CSS.
• Igniter.js for type-safe, feature-based APIs (DDD-style).
• Prisma ORM with Postgres (multi-tenant, organization-based).
• Better Auth for role-based access (admin/owner/member).
• Stripe for payments/subscriptions.
• React Email/Resend for emails, MinIO/AWS S3 for storage.
• Docker for local services; ready for Vercel/Netlify deploy.

📋 Prerequisites

Before using the CLI:

• Node.js: v22+.
• Git: Installed and configured (for cloning).
• Docker Desktop: For local services (Postgres, Redis, MinIO, Mailhog). Start it before running the CLI.
• Package Manager: At least one (Bun recommended; install via bun.sh if needed).
• GitHub Access: Public repo access (HTTPS) or SSH keys set up for private branches.
• Stripe Account (optional): For payments setup during CLI prompts.

Verify:

node --version  # >=18
git --version   # >=2.30
docker --version  # >=20
bun --version   # If using Bun

🛠 Installation

Install globally via npm/Bun/Yarn/pnpm (requires Node.js):

# Using Bun (recommended)
bun add -g saas-boilerplate

# Using npm
npm install -g saas-boilerplate

# Using Yarn
yarn global add saas-boilerplate

# Using pnpm
pnpm add -g saas-boilerplate

Or run directly without global install:

npx saas-boilerplate create my-app --branch main

📖 Usage

The CLI provides three main commands: create (scaffold a new project), dev (start dev mode in an existing project), and lia (configure AI Code Agents).

Creating a New Project

Run the create command to scaffold the boilerplate:

# Basic usage
saas-boilerplate create my-saas-app

# With options
saas-boilerplate create my-saas-app --branch release/2.1.0

# Or with npx
npx saas-boilerplate create my-saas-app --branch main

Interactive Flow

• Project Name: Prompts for name (defaults to argument; validates non-empty).
• GitHub Auth: Choose HTTPS (default, no keys needed) or SSH (faster for frequent use; requires ~/.ssh/id_rsa added to GitHub).
• Package Manager: Select Bun (recommended), Yarn, pnpm, or npm.
• Directory Handling: If folder exists and non-empty, prompts to clear it.
• Stages (with spinners):
  • 1. Installing SaaS Boilerplate: Clones repo, updates package.json name.
  • 2. Setting up project: Installs dependencies.
  • 3. Configuring environment: Sets .env vars (app name, secrets, platform).
  • 4. Starting local development services: docker compose up -d.
  • 5. Setting up database: Runs Prisma migrations.
• Stripe Config (optional): Prompts for publishable/secret keys; adds to .env.
• Dev Server (optional): Prompts to run dev immediately.
• Success Message: Detailed guide with next steps, commands, and troubleshooting.

Example output (abridged):

◇ What is the name of your project? my-saas-app
◇ Choose GitHub authentication method: HTTPS
◇ Choose your preferred package manager: Bun
◑ 1. Installing SaaS Boilerplate... ✓
◑ 2. Setting up project... ✓
◑ 3. Environment configured. ✓
◑ 4. Local development services started. ✓
◑ 5. Database setup complete. ✓
◇ Do you want to configure Stripe for payments now? Yes/No
◇ Start the development server now? Yes/No

🚀 Your my-saas-app project is ready!
[Expanded guide...]

Options

• --branch <branch>: Git branch to clone (default: main). Use for releases like release/2.1.0.
• No other flags; all interactive.

Running Dev Mode

In an existing project directory:

cd my-saas-app
saas-boilerplate-cli dev

• Checks Docker status (prompts to continue if not running).
• Runs docker compose down && up -d (restarts services).
• Installs deps if node_modules missing.
• Starts bun dev (or equivalent; opens http://localhost:3000).
• Handles errors (e.g., port conflicts).

AI Code Agents Configuration (LIA)

Configure AI development assistants with SaaS-specific patterns and Igniter.js awareness:

# Show LIA interactive menu
saas-boilerplate-cli lia

# Generate configurations for specific tools
saas-boilerplate-cli lia generate --targets copilot,cursor,claudecode

# Import existing configurations  
saas-boilerplate-cli lia import --targets claudecode,copilot

# Sync all AI tools
saas-boilerplate-cli lia sync

# Update .gitignore with AI patterns
saas-boilerplate-cli lia gitignore

Interactive LIA Flow

• System Check: Verifies rulesync availability and project configuration.
• Main Menu: Choose between Initialize, Sync, or .gitignore update.
• Tool Selection: Multi-select from 15+ AI tools (GitHub Copilot, Cursor, Claude Code, etc.).
• Configuration: Applies SaaS-specific rules, commands, and MCP configurations.
• Success Feedback: Detailed status with configured tools count and patterns.

During Project Creation

When creating a new project, LIA setup is offered:

◇ Do you want to configure AI Code Agents (LIA) now? Yes/No

If confirmed, it configures preferred tools automatically before starting the dev server.

Supported AI Tools

• Core: GitHub Copilot, Cursor, Claude Code, Codex CLI, Gemini CLI
• Extended: OpenCode, Cline, Roo Code, Qwen Code, Kiro IDE
• Enterprise: Amazon Q Developer CLI, JetBrains Junie, AugmentCode
• Cloud/Edge: Windsurf, Warp

LIA Features

• SaaS Patterns: AI agents understand multi-tenancy, auth flows, payment integration
• Igniter.js Aware: Familiar with type-safe API patterns and DDD structure
• All Features Enabled: Rules, commands, MCP, subagents, ignore files by default
• Zero Installation: Uses npx rulesync - no additional packages required

Example LIA session:

🤖 LIA - AI Code Agents Configuration
✅ Checking system requirements... Ready
◆  What would you like to do with LIA?
│  ● Initialize LIA on my Code Agents (Eg. Cursor, Claude Code, Codex)
│  ○ Sync All Configurations
│  ○ Update .gitignore
└
◆  Select your preferred Code Agents:
│  ● GitHub Copilot
│  ● Cursor  
│  ● Claude Code
│  ● Codex CLI
└
◆  Ready to configure 4 Code Agents? ● Yes / ○ No
◑  Setting up GitHub Copilot... ✓
◑  Setting up Cursor... ✓
◑  Setting up Claude Code... ✓
◑  Setting up Codex CLI... ✓
✅ LIA is ready! All 4 Code Agents are now configured with SaaS Boilerplate patterns.
🚀 Your AI agents are now ready to assist!

LIA Command Reference

• lia - Show interactive configuration menu
• lia generate --targets <tools> - Generate for specific AI tools
• lia import --targets <sources> - Import existing configurations
• lia sync - Sync all AI tools configurations
• lia gitignore - Update .gitignore with AI patterns
• --verbose - Enable detailed output
• --targets - Comma-separated tool list: copilot,cursor,claudecode,codexcli,geminicli,opencode,cline,roocode,qwencode,kiroide,amazonq,junie,augmentcode,windsurf,warp

⚙️ Configuration

• GitHub Auth:
  • HTTPS: No setup; uses public access. If rate-limited, log in to GitHub.
  • SSH: Ensure SSH key is generated (ssh-keygen -t ed25519) and added to GitHub (Settings > SSH keys). Test: ssh -T [e-mail].
• Package Managers:
  • Bun: Fastest; auto-installs if selected.
  • Others: Ensure global install (e.g., npm install -g yarn).
• Environment:
  • CLI sets basics (.env: app name, UUID secret, SMTP for Mailhog, platform).
  • Manual edits: Add Stripe keys, RESEND_API_KEY (prod emails), AWS creds (S3 storage).
• Docker: Services auto-start; volumes persist data (e.g., postgres_data). Customize docker-compose.yml for ports/volumes.

🔧 Commands Reference

Command	Description	Example
create <name> [--branch <branch>]	Scaffold new SaaS project.	saas-boilerplate create app --branch main
dev	Start dev mode (in project dir).	saas-boilerplate dev
lia [subcommand] [options]	Configure AI Code Agents (LIA).	saas-boilerplate lia
lia generate --targets <tools>	Generate for specific AI tools.	saas-boilerplate lia generate --targets copilot,cursor
lia import --targets <sources>	Import existing configs.	saas-boilerplate lia import --targets claudecode
lia sync	Sync all AI configurations.	saas-boilerplate lia sync
lia gitignore	Update .gitignore with AI patterns.	saas-boilerplate lia gitignore

LIA Targets Available: copilot, cursor, claudecode, codexcli, geminicli, opencode, cline, roocode, qwencode, kiroide, amazonq, junie, augmentcode, windsurf, warp

Global Options: --branch, --targets, --verbose, --debug

See the scaffolded project's README.md for full boilerplate docs.

🐛 Troubleshooting

Common issues and fixes:

Git Clone Fails/Hangs

• Network/Auth: Test manual clone: git clone https://github.com/vibe-dev/saas-boilerplate test-clone. For SSH: ssh -T [e-mail].
• Permission Denied: HTTPS: Use GitHub PAT if private. SSH: Add key to ssh-agent (ssh-add ~/.ssh/id_rsa).
• Repo/Branch Not Found: Verify branch exists (e.g., release/2.1.0). Default: main.
• Slow/Large Repo: Use --depth=1 manually; CLI doesn't shallow-clone yet.

Docker Services Fail

• Auth Required (Email Verify): Docker Hub rate limit or unverified account. Run docker logout && docker login (create/verify free account at hub.docker.com).
• Not Running: Start Docker Desktop. Test: docker --version && docker compose ps.
• Port Conflicts: Kill processes: lsof -i :5432 | kill -9 <PID> (Postgres). Edit docker-compose.yml ports.
• Pull Interrupted: Prune: docker system prune -a. Retry: docker compose pull.
• Logs: docker compose logs postgres (or service name).

Dependencies/Install Errors

• Package Manager Missing: Install (e.g., curl -fsSL https://bun.sh/install | bash for Bun).
• Node Version: Upgrade to v18+: Use nvm (nvm install 22).
• Lockfile Conflicts: Delete node_modules + lockfile (bun.lockb/yarn.lock), retry install.

Database/Migrations

• Services Not Ready: Wait 15-30s post-Docker up. Check: docker compose ps.
• Prisma Errors: Run prisma generate manually. Reset DB: docker compose down -v && up -d && db:migrate:dev.
• Connection Refused: Verify DATABASE_URL in .env (local: postgresql://docker:docker@localhost:5432/docker).

Dev Server Issues

• Port 3000 In Use: lsof -i :3000 | kill -9 <PID>.
• Build Fails: Check deps installed; run lint or typecheck.
• Auth/Org Errors: Create first user at /auth/signin; ensure org context.

🤖 LIA Troubleshooting

LIA Configuration Fails

• Rulesync Not Available: Ensure Node.js v22+ and npm are installed. Test: npx rulesync --version.
• No .rulesync Found: Ensure running in SaaS Boilerplate project or run saas-boilerplate create first.
• Network Issues: Rulesync uses internet for initial setup. Check connection and retry.
• Permission Denied: Ensure write access to project directory and .gitignore file.

AI Tools Not Working

• Configuration Not Applied: Restart your IDE/code editor after LIA setup.
• Git Configuration: Run saas-boilerplate lia gitignore to add generated files to .gitignore.
• Tool-Specific Issues: Each AI tool may need enabling or configuration in their respective settings.

LIA Command Errors

• Invalid Targets: Check available tools with help or use comma-separated format: --targets copilot,cursor.
• Verbosity: Use --verbose for detailed error messages and debugging info.
• NPX Issues: Ensure npm is accessible; some environments may need npm install -g npx.

General

• Silent Hangs: Run with DEBUG=* saas-boilerplate create app for verbose logs.
• Windows-Specific: Use Git Bash/WSL; ensure OpenSSH installed for SSH.
• Permissions: Run as non-root; fix with chmod +x index.js if needed.
• Updates: npm update -g saas-boilerplate-cli (or equivalent).

If LIA issues persist, run with --verbose and check console output or open a GitHub issue with error logs, OS, and steps to reproduce.

🤝 Contributing

• Fork the repo.
• Clone: git clone <your-fork> && cd saas-boilerplate-cli.
• Install deps: bun install (or your manager).
• Run locally: bun index.js create test-app (tests setup).
• Make changes; test on fresh dir.
• Commit/PR: Follow conventional commits; add tests if applicable.

See CONTRIBUTING.md for details.

📄 License

MIT License. See LICENSE for details.

Made with ❤️ by Felipe Barcelos. Questions? Open an issue.