CLI Init Flow

CLI Init Deep Dive

This guide explains exactly what happens when you run:

npx seamless-cli my-app

That project-name shorthand runs the same init path as npx seamless-cli init my-app. Running the CLI with no command prints help.

This guide focuses on local project generation, auth wiring, Docker setup, and admin dashboard inclusion.

---

Mental Model

init → prompts → generators → config → ready-to-run app

---

Step 0: Directory Setup

If you pass a project name:

npx seamless-cli my-app

The CLI will:

• Create a new folder
• Ensure it does not already exist
• Use it as the project root

If you run npx seamless-cli init with no project name, it uses the current directory. If that directory is not empty and you are not logged in, the current CLI prints that an existing project was detected and exits; the existing-project integration flow is still future work.

---

Step 1: Interactive Prompts

The CLI asks a series of questions to shape your stack.

Web Framework

• React (Vite)
• Next.js is listed as coming soon, not currently generated

This determines your frontend scaffold.

---

Backend Framework

• Express
• Fastify, FastAPI, and Axum are listed as coming soon, not currently generated

This determines your API server.

---

Mobile App

• None (the default)
• Expo (React Native)

Optional. Picking Expo adds a mobile/ project on @seamless-auth/react-native, signing in against the same API over bearer transport. Pass --mobile=expo to answer without the prompt.

---

Auth Mode

• Docker (recommended)
• Local dev server (advanced)

Docker mode:

• Runs full auth stack in containers
• Closest to production

Local mode:

• Generates the auth server source into ./auth
• Still relies on Docker for the full local stack
• Prompts about Docker, but the current source enables Docker either way because it is required for the full generated stack

---

Admin Dashboard

You choose whether to include the Admin UI.

If enabled:

Admin Source

• Docker image (recommended)
• Source (for customization)

---

Step 2: Generators Run

Based on your answers, the CLI executes generators.

Frontend

await generateReactStarter({ root })

Creates:

• React app (Vite)
• Auth-aware starter frontend

---

Backend

await generateExpressStarter({ root })

Creates:

• Express API
• Auth-ready endpoints

---

Auth Server

If using local mode:

await generateAuthServer({ root }, 'local')

This generates the Seamless Auth server locally.

---

Docker Setup

await generateDockerCompose(root, {
  authMode,
  adminMode,
  includeAdmin,
})

Creates:

• Postgres container
• Auth server container
• Admin UI container (optional)

---

Step 3: Environment Configuration

The CLI wires environment variables automatically.

API

configureApiEnv(root, sharedConfig)

Web

configureWebEnv(root)

Auth

configureAuthLocalEnv(root)

This ensures:

• Services can communicate
• URLs and ports are aligned

---

Step 4: Project Config File

generateSeamlessConfig(root, { ... })

Creates:

seamless.config.json

This file stores:

• Framework choices
• Auth mode
• Admin configuration

---

Step 5: Final Output

The CLI prints next steps. In the Docker-backed path, those are:

• docker compose up
• seamless bootstrap-admin
• complete registration in the browser

It also prints the expected local service URLs for auth, API, web, and admin.

---

Generated Project Structure

my-app/
  web/
  api/
  auth/                  # local auth mode only
  admin/                 # admin source mode only
  docker-compose.yml
  seamless.config.json
  README.md

---

What Gets Wired Automatically

• Auth endpoints
• Session handling
• Secure cookies
• Frontend SDK integration
• Backend auth validation

---

Key Design Decisions

Opinionated Defaults

The CLI chooses:

• Secure session handling
• Passwordless flows
• Best-practice structure

---

Full-Stack by Default

You always get:

• web/ frontend starter
• api/ backend starter
• local Docker Compose wiring
• seamless.config.json
• auth server runtime wiring

You may also get:

• auth/ source when local auth mode is selected
• admin/ source when admin source mode is selected

---

Docker-First

Even in local mode, Docker is used to ensure consistency.

---

Common Pitfalls

• Running in a non-empty directory
• Skipping Docker setup
• Misunderstanding auth mode differences

---

Prompt for AI Help

Copy this into ChatGPT:

“Explain what happens internally when I run seamless-cli init and how the project is generated.”

---

Next Step

→ Learn how Docker and local services work together