Skip to content

CLI Init Flow

This guide explains exactly what happens when you run:

Terminal window
npx seamless-cli init my-app

Scaffolding 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.


init → directory check → template prompts → copy templates → auth + compose → env → config

Starter 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.


If you pass a project name:

Terminal window
npx seamless-cli init my-app

The 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.


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.

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.


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/.


  • 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.


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.


  • 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.


  • Served by your API at /console (recommended)
  • Separate container from the official Docker image
  • Separate container from the dashboard source, unpacked into ./admin for 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.


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).

Terminal window
npx seamless-cli init my-app --oauth --fastify

The 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).

--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:

  • Google
  • 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/callback

Under --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.


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.


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 ./auth in 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).


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.


generateSeamlessConfig(root, { ... })

Creates:

seamless.config.json

This file stores:

  • the web, API, and mobile frameworks (and whether the web app is full-stack)
  • the auth mode, with the auth image or ./auth path
  • the admin console mode, with its image, ./admin path, or /console URL

The CLI prints the included services and next steps. In the local path, those are:

  1. docker compose up
  2. 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.


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.json

Each starter directory has its own README.md from the template.


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

The CLI chooses:

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

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.


Every local scaffold writes docker-compose.yml. Even in local auth mode, Postgres and your app run on Compose for consistency.


  • Running init in 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

→ Learn how Docker and local services work together