What You Just Built
- Web app - API - Auth server - Optional admin dashboard - Local Docker-based infrastructure
Scaffold the recommended local stack with no prompts (safe in CI, scripts, and agents, since it never waits for input):
npx seamless-cli init my-app --local --yes --email=you@example.comcd my-appdocker compose up--local scaffolds a self-hosted stack, --yes takes the recommended answer for every remaining
question, and --email sets the owner address that becomes the first admin when you register with
it. The result is a React web app, an Express API, the auth server as a Docker image, and the admin
console served by the API at /console. The full flag list is in the
CLI Command Reference.
This guide walks through the fastest supported way to run Seamless Auth yourself: scaffold a project with the CLI, start the stack locally, and sign in as the first admin. The steps below use the interactive form so you can see each choice.
>=22)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:
You can inspect the CLI here:
Before starting, you can inspect available commands:
npx seamless-cli --helpThis will show:
init, templates, check, and the instance commands such as users and
config)check is the command for validating a project init generated. verify is a conformance suite
for Seamless contributors and needs a clone of the auth server’s source.
Every command also documents itself, for example npx seamless-cli init --help.
Run the CLI:
npx seamless-cli init my-appcd my-appScaffolding always goes through init. A bare project name (npx seamless-cli my-app) is rejected
as an unknown command, and running the CLI with no command prints help.
The CLI will guide you through:
/console, a separate container, or
not at all)
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.jsonThe exact shape depends on the options you selected, but the CLI always wires the generated pieces together for local development.
The CLI generates a Docker-based development environment.
Start services:
docker compose upThis will:
Open:
http://localhost:5173You should see the starter UI with:

If http://localhost:5173 shows a different app, another dev server (often Vite, whose default port
is also 5173) holds the port on [::1], and your browser reaches it before the stack. Stop that
server, or find it with:
lsof -nP -iTCP:5173 -sTCP:LISTENnpx seamless-cli check, run in the project, reports a port another program holds.
If the API container exits with an error such as
does not provide an export named 'requirePermission', Docker reused images built for an older
project in a folder with the same name. Rebuild them:
docker compose up --buildThere is no separate admin command. init wrote the email you gave it to the auth server as
OWNER_EMAIL, and the auth server grants admin:write to the account created with that address.
The starter lists it among your roles as admin:write, not admin.
In the web app at http://localhost:5173, register with the email you gave init.
When asked for a code, get it from the project directory. The local stack sends no email:
npx seamless-cli owner-codeIt prints a code for the owner address init recorded.
Enter the code, and enroll a passkey when prompted.
You are now signed in as an admin. Open the admin console at http://localhost:3000/console (or
http://localhost:5174 if you chose a separate dashboard container).
You now have a local stack with:
initnpx seamless-cli check)What You Just Built
Continue to Create Your First User for what happens during sign-in, or Create Your First Admin for how the owner grant works.
Before real users depend on it, read Go Passwordless Without Locking Anyone Out: set up recovery codes and a break-glass admin, and dry-run sign-in policy changes before you publish them.