create-seamless

create-seamless is a CLI for bootstrapping applications with Seamless Auth, an open source, passwordless authentication system.

It guides you through creating a fully working authentication stack with a web app, API, and auth server that are already connected and ready to run.

Getting started

Run the CLI with npx:

npx create-seamless my-app

Or run it in your current directory:

npx create-seamless

You’ll be guided through a short setup process where you can choose:

• Whether to create a web application
• Whether to create an API server
• How to run the auth server (local or Docker)
• Whether to run everything with Docker

What gets created

Depending on your selections, the CLI generates a project like this:

my-app/
├─ auth/        # Seamless Auth server (optional)
├─ web/         # React web application (optional)
├─ api/         # Express API server (optional)
├─ docker-compose.yml (optional)
└─ README.md

All services are preconfigured to work together.

• Web calls the API
• API communicates with the auth server
• Auth manages sessions and tokens

No manual wiring is required.

Running your project

Option 1: Docker

If you choose Docker during setup:

docker compose up

This starts:

• PostgreSQL
• Auth server
• API server
• Web app

All services are configured to communicate correctly inside the container network.

Option 2: Local development

If you choose to run locally:

1. Start PostgreSQL

Make sure you have a local PostgreSQL instance running on port 5432.

2. Start the auth server

cd auth
npm install

npm run db:create
npm run db:migrate

npm run dev

3. Start the API

cd api
npm install
npm run dev

4. Start the web app

cd web
npm install
npm run dev

What is configured for you

create-seamless handles the parts that are usually difficult to get right:

• Shared API service tokens
• JWT signing configuration
• JWKS key generation for production mode
• Cross-service environment variables
• CORS and cookie-based session handling

Everything is aligned across services so the system works immediately after setup.

Included projects

create-seamless pulls from the following repositories:

• Seamless Auth API https://github.com/fells-code/seamless-auth-api

• Seamless Auth React Starter https://github.com/fells-code/seamless-auth-starter-react

• Seamless Auth API Starter https://github.com/fells-code/seamless-auth-starter-express

Each project can be used independently, but the CLI connects them into a working system.

Documentation

Full documentation is available at:

https://docs.seamlessauth.com

Philosophy

Seamless Auth is built around a few principles:

• Passwordless authentication only
• No redirects or third-party auth providers
• Self-hosted by default
• Production-shaped local development
• Explicit configuration over hidden behavior

create-seamless exists to make this setup fast and repeatable.

Requirements

• Node.js 18 or newer
• npm or pnpm
• Docker (optional)

License

AGPL-3.0-only © 2026 Fells Code LLC

This license ensures:

• transparency of security-critical code
• freedom to self-host and modify
• sustainability of the managed service offering

See LICENSE for details.