Skip to content
Seamless Auth Docs

Quickstart

Quickstart

Section titled “Quickstart”

This guide walks through the fastest supported way to get Seamless Auth running locally: scaffold a project with the CLI, start the stack, and complete the first admin bootstrap flow.

What you will need to complete this walkthrough

Section titled “What you will need to complete this walkthrough”
  • A machine with node > 20.11.x installed
  • A way to run a postgres database locally (we recommend via a container)
  • A terminal like application or interface
  • A web browser

What is the CLI?

Section titled “What is the CLI?”

The Seamless Auth CLI is published as seamless-cli and exposes the seamless binary. It scaffolds a working local project around the auth ecosystem.

Today it is primarily used to:

  • Scaffold the web app and API starter
  • Configure the auth server in Docker or local mode
  • Optionally include the admin dashboard
  • Generate local secrets and service-to-service wiring
  • Validate the generated local stack
  • Bootstrap the first admin user

Explore the Project

Section titled “Explore the Project”

You can inspect the CLI here:

CLI Help Menu

Section titled “CLI Help Menu”

Before starting, you can inspect available commands:

Terminal window
npx seamless-cli --help

This will show:

  • Available commands (init, check, bootstrap-admin)
  • Usage patterns
  • Default CLI behavior

Step 1: Initialize a Project

Section titled “Step 1: Initialize a Project”

Run the CLI:

Terminal window
npx seamless-cli init my-app
cd my-app

You can also use the project-name shorthand:

Terminal window
npx seamless-cli my-app

Running the CLI with no command prints help.

Step 2: Interactive Setup

Section titled “Step 2: Interactive Setup”

The CLI will guide you through:

  • The frontend framework
  • The backend framework
  • How to run the auth server
  • Whether to include the admin dashboard
  • Whether to use the dashboard image or source
Seamless CLI init output
Use seamless-cli init to scaffold a full-stack local auth project

Step 3: Generated Project Structure

Section titled “Step 3: Generated Project Structure”

After setup, your project will look like:

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

The exact shape depends on the options you selected, but the CLI always wires the generated pieces together for local development.

Section titled “Step 4: Start with Docker (Recommended)”

The CLI generates a Docker-based development environment.

Start services:

Terminal window
docker compose up

This will:

  • Start Postgres
  • Start the Seamless Auth server
  • Start a template web application
  • Start a template API server
  • Start the admin dashboard if you included it
  • Use the generated local config and service tokens

Step 5: View the App

Section titled “Step 5: View the App”

Open:

http://localhost:5173

You should see the starter UI with:

  • Login / signup flow
  • Passwordless authentication
  • Session management
Seamless Auth starter UI
Seamless Auth starter UI

Step 6: Bootstrap Your First Admin

Section titled “Step 6: Bootstrap Your First Admin”

Once the stack is running, create your first admin invite:

Terminal window
npx seamless-cli bootstrap-admin admin@example.com

If the CLI can resolve the bootstrap secret locally, it will use it automatically. Otherwise it will prompt you for the secret.

After the invite is created:

  • open the registration URL
  • complete the registration flow with the invited email
  • the resulting user will receive admin access

What Just Happened

Section titled “What Just Happened”

You now have a local stack with:

  • A full-stack application
  • A running auth server
  • Connected frontend and backend services
  • Passwordless authentication enabled
  • A bootstrap path for your first admin user
  • A CLI that can also check the generated stack

What You Just Built

  • Web app - API - Auth server - Optional admin dashboard - Local Docker-based infrastructure

Prompt for AI Help

Section titled “Prompt for AI Help”

Copy this into ChatGPT:

“Help me customize a Seamless Auth project created with seamless-cli. I want to add roles, protect routes, and understand which package does what.”

Next Step

Section titled “Next Step”

Continue to Create Your First User.