CLI Init Flow
This guide explains exactly what happens when you run:
npx seamless-cli init my-appScaffolding always goes through init; a bare project name is rejected as an unknown command.
Running the CLI with no command prints help.
This guide focuses on the local (self-hosted) scaffold: template selection, auth wiring, Docker
setup, and admin console inclusion. When you are signed in to the portal, init can instead connect
the project to a managed application; see the Managed Quickstart.
Mental Model
Section titled “Mental Model”init → directory check → template prompts → copy templates → auth + compose → env → configStarter source is not generated by code in the CLI. It comes from a template registry, and each template carries a small manifest that tells the CLI where it goes and which env values it needs.
Step 0: Directory Setup
Section titled “Step 0: Directory Setup”If you pass a project name:
npx seamless-cli init my-appThe CLI creates ./my-app and uses it as the project root. If that directory already exists,
init stops with Directory already exists. If the scaffold fails or you cancel partway, the
directory it just created is removed, so a retry starts clean.
If you run npx seamless-cli init with no project name, it uses the current directory. A
non-empty directory does not simply exit; what happens depends on whether a managed application is
available:
| Situation | Behavior |
|---|---|
| Signed in to the portal with a provisioned application | Asks whether to connect the existing project to a managed application, or scaffold a new project here |
| Not signed in, or no provisioned application | Asks you to confirm scaffolding over the existing files; declining writes nothing |
--app <id> |
Connects the existing project to that application without asking |
--yes without --force |
Refuses, because starter files overwrite anything with the same name |
--yes --force |
Scaffolds into the directory |
Connecting an existing project does not generate source. It issues the application’s service token
and writes AUTH_SERVER_URL, API_SERVICE_TOKEN, JWKS_KID, and COOKIE_SIGNING_KEY (plus
DATABASE_URL when a managed database is provisioned and none is set) into api/.env, keeping any
keys already there. With no api/ directory it prints the values to paste in by hand.
Step 1: Interactive Prompts
Section titled “Step 1: Interactive Prompts”The CLI asks a series of questions to shape your stack. The framework options are not a hardcoded
list: they are read from the template registry, in registry order, so a new starter appears here
when it is added to the registry. Templates marked beta are labelled (beta), and coming-soon
templates are shown but cannot be selected.
Web example
Section titled “Web example”Every web and full-stack template in the registry. As of the pinned registry ref (v0.19.1) that is:
- React (Vite) - basic example
- React (Vite) - OAuth example
- Angular (beta)
- Vue (Vite) (beta)
- SvelteKit (single-page app) (beta)
- Next.js (App Router) - full-stack example (beta)
Next.js is a full-stack template: it lands in web/ and serves /auth itself, so a project built
on it has no api/ layer and the backend question is skipped. See Next.js.
Backend framework
Section titled “Backend framework”Every api template in the registry. As of v0.19.1:
- Express
- Fastify (beta)
- Go (Gin) (beta)
- Rust (Axum) (beta)
- Python (FastAPI) (beta)
This determines your API server in api/.
Mobile app
Section titled “Mobile app”- No mobile app (the default)
- Expo (React Native) - mobile example (beta)
Optional. Picking Expo adds a mobile/ project on @seamless-auth/react-native, signing in
against the same API over bearer transport.
Owner email
Section titled “Owner email”The address you give here is written to the auth server as the owner, so registering with it makes you the first admin. When you are signed in to the portal, it is prefilled from that session.
Auth server
Section titled “Auth server”- Docker container (recommended)
- Local dev server (advanced)
Docker mode runs the auth server from the published ghcr.io/fells-code/seamless-auth-api
image, which is closest to production.
Local mode clones the seamless-auth-api source into ./auth and configures its .env. The
rest of the stack (Postgres, your app) still runs on Docker Compose.
Admin console
Section titled “Admin console”- Served by your API at
/console(recommended) - Separate container from the official Docker image
- Separate container from the dashboard source, unpacked into
./adminfor modification - Don’t include the admin console
With a full-stack template such as Next.js, only two options apply. Starting with seamless-cli 0.20.0 (fells-code/seamless-cli#239),
api (the default, and the default under --yes) has the web app serve the console
at http://localhost:5173/console through createSeamlessConsoleProxy
(Next.js: Admin Console). The CLI writes SERVE_ADMIN_CONSOLE=true
into web/.env, the same switch the Express and Fastify starters use, and sets
SERVE_ADMIN_DASHBOARD=true on the auth server. none leaves the console out. --admin=image and
--admin=source are refused, because a dashboard container on :5174 would call the app’s /auth
cross-origin, which the Next.js route handler does not allow. A templates release whose Next.js
starter has no /console route is scaffolded without the console, with a warning; an explicit
--admin=api with such a release is an error. Earlier CLI releases set the console to none for
full-stack templates without asking.
Template Flags
Section titled “Template Flags”Every template can be selected on the command line, which answers that layer’s prompt. The flags are
registry-driven: each template answers to --<id>, and some also declare a shorter --<alias>.
seamless templates list prints the id, kind, framework, flags, and status of every template the
current registry offers, so treat it as the authoritative list. As of v0.19.1:
| Template | Kind | Flags | Status |
|---|---|---|---|
| React (Vite) - basic example | web | --basic, --react-vite |
stable |
| React (Vite) - OAuth example | web | --oauth, --react-oauth |
stable |
| Angular | web | --angular |
beta |
| Vue (Vite) | web | --vue |
beta |
| SvelteKit (single-page app) | web | --svelte |
beta |
| Express | api | --express |
stable |
| Fastify | api | --fastify |
beta |
| Go (Gin) | api | --gin |
beta |
| Rust (Axum) | api | --axum |
beta |
| Python (FastAPI) | api | --fastapi |
beta |
| Expo (React Native) - mobile example | mobile | --mobile, --expo |
beta |
| Next.js (App Router) - full-stack example | fullstack | --nextjs |
beta |
Status is the starter template’s status in the registry, not the adapter package’s. The Fastify, Gin, Axum, FastAPI, and Next.js templates are beta; the adapters under them are official (see Current Official Coverage and the Python, Go, and Rust pages).
npx seamless-cli init my-app --oauth --fastifyThe long forms --web=<id|alias>, --api=<id|alias>, and --mobile=<id|alias> name the layer
explicitly and take the same values. Since seamless-cli 0.20.0 a bare --mobile (with no value
after it) selects the Expo template through its mobile alias, so seamless init --mobile my-app
keeps my-app as the project name. A bare --web or --api is an error, because neither is a
template alias. An unknown flag, two templates for the same layer, or an api
template next to a full-stack one is an error reported before any directory is created. Run
seamless init --help for the non-interactive flags (--yes, --email, --auth, --admin,
--force).
The --oauth starter
Section titled “The --oauth starter”--oauth selects the React (Vite) OAuth example, so the web prompt is skipped; the backend, mobile,
owner email, auth server, and admin console questions are still asked. Because that template’s
manifest opts into OAuth setup, the local scaffold then asks which providers to enable:
- GitHub
- Microsoft
- GitLab
For each provider you pick, it asks for the client ID and client secret (Microsoft also asks for your
directory (tenant) ID, a GUID; common, organizations, and consumers are refused). The chosen
providers are written into the auth server’s environment as OAUTH_PROVIDERS, with each secret in
its own <PROVIDER>_CLIENT_SECRET variable. Any credential can be left blank: that provider is
scaffolded disabled so the stack still boots, and the summary lists it under
Needs credentials before use. Apple is not offered, because its client secret is a signed JWT
rather than a pasted value.
After scaffolding, the CLI prints the redirect URI to register with each provider:
http://localhost:5173/oauth/callbackUnder --yes the provider prompt is skipped and the starter is scaffolded with none configured; add
them later with seamless config oauth-providers add. The provider prompt runs only in the local
scaffold; connecting to a managed application does not ask it.
Step 2: Templates Are Copied In
Section titled “Step 2: Templates Are Copied In”The starters live in the
fells-code/seamless-templates repository. Its
registry.json lists every template, and each template directory (for example
templates/web/react-oauth) holds the starter source plus a template.json manifest.
The CLI pins the repository to a tag, so a given CLI version always produces the same project. The
current CLI (0.23.1) pins
v0.19.1. openTemplateSource()
resolves where templates are read from:
| Source | When | Behavior |
|---|---|---|
| Published repository | Default | Fetches registry.json at the pinned ref, then downloads the repository archive once |
Published repository, ref |
SEAMLESS_TEMPLATES_REF is set |
Same, at the ref you name instead of the pinned tag |
| Local checkout | SEAMLESS_TEMPLATES_DIR is set |
Reads registry.json and the templates from that directory; takes precedence over the ref |
Before anything is copied, the CLI reads each selected template’s manifest and checks its
requires.cliMin, failing with an upgrade message if your CLI is older. At v0.19.1 the Express,
Fastify, Gin, Axum, FastAPI, and Next.js starters require seamless-cli 0.19.0 (they read {{authServerIssuer}}), Expo
requires 0.16.0, and the React (Vite), Angular, Vue, and SvelteKit starters require 0.3.0. Pointing an older CLI at that tag
with SEAMLESS_TEMPLATES_REF therefore fails for the server-side starters. Each template is then
copied into the manifest’s targetDir (web, api, or mobile). Build output and local-only
files such as node_modules, dist, .git, and .env are never copied.
Step 3: Auth Server And Docker Compose
Section titled “Step 3: Auth Server And Docker Compose”In local auth mode the CLI clones the auth server into ./auth and writes its .env with
configureAuthLocalEnv. With admin source mode it unpacks the admin dashboard into ./admin.
It then always writes docker-compose.yml. The file defines:
- a Postgres container
- the auth server (the published image in Docker mode, or a build of
./authin local mode) - your app services
- an admin dashboard container, in the image and source admin modes
Ports are published on 127.0.0.1 only. This step also produces the shared values the next step
needs: the API service token and the service token kid (JWKS_KID).
Step 4: Environment Configuration
Section titled “Step 4: Environment Configuration”Each template’s env is wired by applyTemplateEnv(dir, manifest, ctx). It copies the file named by
the manifest’s env.fromExample (usually .env.example) to .env, then applies env.set,
resolving {{placeholder}} tokens against values the CLI computed for this scaffold. A starter that
needs a new value declares it in its manifest rather than in CLI code.
For example, the Express template’s manifest sets:
{ "id": "express", "targetDir": "api", "env": { "fromExample": ".env.example", "set": { "AUTH_SERVER_URL": "{{authServerUrl}}", "API_SERVICE_TOKEN": "{{apiToken}}", "JWKS_KID": "{{jwksKid}}", "COOKIE_SIGNING_KEY": "{{secret:32}}", "SERVE_ADMIN_CONSOLE": "{{serveAdminConsole}}", "DATABASE_URL": "{{databaseUrl}}" } }}| Placeholder | Local scaffold value |
|---|---|
{{authServerUrl}} |
http://localhost:5312 |
{{authServerIssuer}} |
http://auth:5312, the issuer the local auth container signs with (seamless-cli 0.19.0 or later; the instance URL on a managed instance) |
{{apiUrl}} |
http://localhost:3000 |
{{apiToken}} |
The service token shared with the auth server |
{{jwksKid}} |
The kid header on the adapter’s service tokens (JWKS_KID), not the auth server’s signing key id |
{{serveAdminConsole}} |
true when the admin console is served by the API, else false |
{{databaseUrl}} |
Empty; the local starter uses its discrete DB_* values |
{{secret:N}} |
A freshly generated secret: N random bytes, hex-encoded |
An unknown placeholder, or one with no value in the current configuration, fails the scaffold
instead of writing a broken .env.
Step 5: Project Config File
Section titled “Step 5: Project Config File”generateSeamlessConfig(root, { ... })Creates:
seamless.config.jsonThis file stores:
- the web, API, and mobile frameworks (and whether the web app is full-stack)
- the auth mode, with the auth image or
./authpath - the admin console mode, with its image,
./adminpath, or/consoleURL
Step 6: Final Output
Section titled “Step 6: Final Output”The CLI prints the included services and next steps. In the local path, those are:
docker compose up- register in the browser with the owner email you gave
init, which makes that account an admin
It also prints the local service URLs: auth on 5312, API on 3000, web on 5173, and the admin
console at http://localhost:3000/console or http://localhost:5174, depending on the admin mode
(http://localhost:5173/console for a full-stack template in api mode).
With the --oauth starter it adds the OAuth provider summary and redirect URI.
Generated Project Structure
Section titled “Generated Project Structure”my-app/ web/ # web or full-stack template api/ # api template (absent for a full-stack template) mobile/ # only when a mobile template is chosen auth/ # local auth mode only admin/ # admin source mode only docker-compose.yml seamless.config.jsonEach starter directory has its own README.md from the template.
What Gets Wired Automatically
Section titled “What Gets Wired Automatically”- Auth endpoints
- Session handling
- Secure cookies
- Frontend SDK integration
- Backend auth validation
Key Design Decisions
Section titled “Key Design Decisions”Opinionated Defaults
Section titled “Opinionated Defaults”The CLI chooses:
- Secure session handling
- Passwordless flows
- Best-practice structure
Registry-Driven Starters
Section titled “Registry-Driven Starters”Adding or changing a starter is a change to seamless-templates, not to the CLI. The registry
decides what the prompts and flags offer, and each manifest decides its target directory, env
values, and minimum CLI version.
Docker-First
Section titled “Docker-First”Every local scaffold writes docker-compose.yml. Even in local auth mode, Postgres and your app run
on Compose for consistency.
Common Pitfalls
Section titled “Common Pitfalls”- Running
initin a non-empty directory and overwriting files with the same name - Skipping Docker setup
- Misunderstanding auth mode differences
- Leaving OAuth credentials blank and expecting that provider to work before you fill them in
Next Step
Section titled “Next Step”→ Learn how Docker and local services work together