Seamless Auth CLI
The Seamless Auth CLI is published as seamless-cli and exposes the seamless binary. It scaffolds
a self-hosted local project, checks the generated stack, verifies auth conformance, and also acts as
an authenticated client against a running Seamless Auth instance (log in, inspect sessions, and run
admin operations).
Current commands cover:
- scaffold a Seamless Auth project from the starter template registry (React, Next.js, Express, Fastify, Expo)
- add Seamless Auth to an existing project with
seamless add - configure the auth server in Docker or local-source mode
- optionally include the admin dashboard
- validate generated config, Docker Compose, containers, and local health endpoints
- make the owner email you give
initthe first admin - verify the full auth surface with the
seamless verifyconformance harness - log in to an instance and manage the active profile, session, and account
- run admin
config,users, andorgoperations against an instance
The current ../seamless-cli source does not ship deploy, destroy, or contribute commands.
Mental Model
Section titled “Mental Model”seamless-cli package -> seamless binary -> init local project -> check local runtime -> register as the owner, who becomes the first adminInstallation
Section titled “Installation”No global install is required. Use the package through npx:
npx seamless-cli --helpIf installed globally or linked locally, run the binary directly:
seamless --helpThe package is named seamless-cli; the executable command is seamless.
Core Commands
Section titled “Core Commands”npx seamless-cli init my-appCreates a new Seamless Auth project. The web, backend, and optional mobile starters are chosen from
the seamless-templates registry, and the
project also gets Docker Compose wiring, seamless.config.json, and either a Docker-based auth
server or local auth server source depending on your prompt choices. It also asks for your email,
which becomes the owner: registering with that address makes you the first admin.
Template flags such as --oauth (the OAuth example, which also prompts for Google, GitHub,
Microsoft, and GitLab providers) skip a layer’s prompt. Run seamless templates list to see them,
and see the CLI Init Flow for what each step does.
npx seamless-cli add --local --email=you@example.comnpx seamless-cli add --app <application-id>Adds Seamless Auth to a project you already have. It finds an Express, Fastify, Go, Axum, FastAPI,
or Django backend and a React, Angular, Vue, or SvelteKit web app, connects a local auth server
(written to seamless/) or a managed application, writes the backend’s .env and the web app’s
API URL, installs the packages, and prints the code to add. It never edits your source files.
Next.js is not wired. See Add Seamless Auth To An Existing App.
npx seamless-cli checknpx seamless-cli check --strictValidates the generated project shape and runtime:
seamless.config.json- configured web, API, and mobile paths
- Docker availability,
docker-compose.yml, and the expected running containers - health endpoints for the API, the auth server, and the admin console (wherever the project’s admin mode serves it)
Every check runs and reports. Without --strict the command exits 0 even when a check fails; with
--strict it exits 1 on any failure, which suits CI. For a managed project the Docker checks are
skipped and the managed instance’s health endpoint is probed instead. The
CLI command reference lists every probe.
It does not check Terraform, AWS CLI, or deployment state.
verify
Section titled “verify”seamless verifyseamless verify --localRuns the cross-package auth conformance harness: it stands up the ecosystem with Docker Compose and
runs a Playwright matrix across the api, adapter, and React (browser) layers, then prints a flow x
layer pass/fail grid. Use --local to build the @seamless-auth/* packages from local source
(pre-publish contract testing); the default tests the published packages. See the
CLI command reference for all flags and environment overrides.
Account And Instance Commands
Section titled “Account And Instance Commands”Beyond scaffolding, the CLI can authenticate against a running Seamless Auth instance and act as a client. It targets whichever instance is set in the active profile.
profile
Section titled “profile”seamless profile add work --instance-url <your-auth-server-url>seamless profile listseamless profile use workseamless profile remove workOn the managed path, --instance-url is your application’s Auth Server URL, copied from
Credentials → Auth API Configuration in the portal. Profiles are named pointers to Seamless
Auth instances, stored in ~/.config/seamless/config.json
(respects XDG_CONFIG_HOME). The config file holds only non-secret instance and identity metadata,
not tokens. Set the active profile per command with --profile <name> or the SEAMLESS_PROFILE
environment variable.
login, whoami, logout
Section titled “login, whoami, logout”seamless login # email OTP against the active profile's instanceseamless whoami # show the current identity, profile, and instance URLseamless logout # end the session and clear local tokensseamless logout --all # revoke every session first, then clear local tokenslogin authenticates with email OTP and stores the session in the OS keychain (macOS Keychain,
Windows Credential Manager, or Linux Secret Service), not in a plaintext file.
sessions
Section titled “sessions”seamless sessions listseamless sessions revoke <id>seamless sessions revoke --allLists and revokes sessions for the logged-in user.
Admin commands
Section titled “Admin commands”With an admin role on the target instance, the CLI can also run config, users, and org
operations. See the CLI command reference for the full flag surface.
CLI Behavior
Section titled “CLI Behavior”If no command is provided, the CLI prints help. Scaffolding always goes through init: a bare
project name such as npx seamless-cli my-app is rejected as an unknown command.
The same behavior applies to the binary:
seamless my-appWhat Happens During init
Section titled “What Happens During init”The CLI will:
- Ask configuration questions, with framework options read from the template registry
- Copy the chosen web, API, and mobile templates into the project
- Configure the auth server in Docker or local-source mode
- Optionally include the admin console
- Generate Docker Compose, each starter’s
.env, andseamless.config.json
See the CLI Init Flow for the details of each step.
Generated Files
Section titled “Generated Files”web/api/ # absent for a full-stack templatemobile/ # only when a mobile template is chosenauth/ # only in local auth modeadmin/ # only in admin source modedocker-compose.ymlseamless.config.jsonDesign Philosophy
Section titled “Design Philosophy”The CLI is built to be:
- opinionated: secure defaults and a known project shape
- guided: interactive prompts for local stack generation
- explicit: generated config and service wiring are visible in the project
- local-first: the current source focuses on a repeatable development stack
Current Boundaries
Section titled “Current Boundaries”seamless add wires an existing project’s environment and packages and prints the code, but does
not edit source files, and does not support Next.js. See
Add Seamless Auth To An Existing App.
Deployment automation is not part of the current seamless-cli command surface. Keep deployment
docs status-based until deployment commands ship again in source.
Next Step
Section titled “Next Step”Continue to CLI Init Deep Dive.