CLI Command Reference
This page summarizes the current public command surface of seamless-cli.
The npm package is named seamless-cli. The executable binary is named seamless.
Command Summary
Section titled “Command Summary”| Command | Purpose |
|---|---|
seamless init [project-name] |
Scaffold a project, either a local self-hosted stack or connected to a managed application |
seamless add [path] |
Add Seamless Auth to an existing project: connect an auth server, write .env, install, print the code |
seamless templates list |
List the starters init can scaffold and the flags that select them |
seamless check [--strict] |
Validate generated project config, Docker, Compose, containers, and local health endpoints |
seamless owner-code [email] |
Print a one-time code for the owner of a local stack, to finish registering the first admin |
seamless verify [flags] |
Run the cross-package auth conformance harness (api / adapter / react matrix) |
seamless profile <sub> |
Manage the instances the CLI targets, and sign in to one with profile login |
seamless clients <sub> |
Register and change the OIDC clients on an instance (admin) |
seamless login [identifier] |
Sign in to the Seamless portal (managed control plane) with email OTP |
seamless apps <list|get> |
Show the managed applications your portal account owns |
seamless whoami |
Show the identity and instance URL behind the portal session, or an instance profile |
seamless logout [--all] |
End the session and clear local tokens |
seamless sessions <sub> |
List or revoke sessions for the logged-in user |
seamless config <sub> |
Read and write instance system configuration (admin) |
seamless users <sub> |
Admin user management (admin) |
seamless org <sub> |
Admin organization and membership management (admin) |
seamless migrate <source> |
Import users from CSV, Entra ID, Auth0, or Cognito, as a dry run unless --apply (admin) |
seamless migrate assess |
Write a migration readiness report from the source alone, with no instance or login |
seamless help [command] |
Print usage, for every command or for one |
seamless --help |
Print usage |
seamless --version |
Print the installed CLI version |
The init, add, templates, check, and verify commands are for building and testing a stack.
login and apps use your portal account. whoami and logout act on the portal session by
default and on an instance with --profile <name>. The profile, sessions, config, users,
org, and migrate commands act as an authenticated client against a running instance (managed or
self-hosted), signed in with seamless profile login, except migrate assess, which reads only the
source.
There is no bootstrap-admin command. The first admin is the account registered with the owner
email you give init, and owner-code prints the code that registration asks for. See
Create Your First Admin.
Use npx seamless-cli ... when you do not have the package installed globally:
npx seamless-cli init my-appnpx seamless-cli checkseamless init my-appIf you omit the project name:
seamless initThe CLI uses the current directory. If the directory is not empty, init asks whether to connect it
to a managed application or scaffold in place, because starter files overwrite anything with the
same name. To add Seamless Auth to a project you already have, use add instead.
What it does
Section titled “What it does”- prompts for web and backend templates read from the template registry, or takes a template flag
- prompts for an optional mobile app (Expo), or takes
--mobile=expoto skip the prompt - prompts for the owner email, which becomes the admin when you register (prefilled from your
portal session when you are signed in), or takes
--email - prompts for auth mode
- optionally includes the admin dashboard (for a full-stack web template, served by the web app at
/consoleor left out, starting with seamless-cli 0.20.0, fells-code/seamless-cli#239) - generates a working local stack
- writes
seamless.config.json - creates
docker-compose.yml
The mobile app lands in mobile/ next to the web and API projects, wired to the same API with
@seamless-auth/react-native. It is not part of the Docker stack: run it with
cd mobile && npm install && npx expo start, which is the command init prints. An Android
emulator reaches the API at http://10.0.2.2:3000, so set EXPO_PUBLIC_API_URL in mobile/.env
when you use one. See React Native SDK.
Current generated stack
Section titled “Current generated stack”The starters come from the fells-code/seamless-templates
registry at the tag the CLI pins (v0.17.0 as of seamless-cli 0.20.0). As of that tag the generated path covers:
- React (Vite) or Next.js (full-stack, beta template) for the web app
- Express or Fastify (beta template) for the backend
- an optional Expo (beta) mobile app
- Seamless Auth API in Docker or local source mode
- an admin console served by the API at
/console, as a separate image or source container, or none
Template flags
Section titled “Template flags”seamless init my-app --oauthseamless init my-app --web=nextjsseamless templates listEach template answers to --<id>, and some also declare a shorter --<alias> (for example
--oauth and --react-oauth select the same starter). A template flag answers that layer’s prompt.
--web=, --api=, and --mobile= take the same ids and aliases and name the layer explicitly. The
flags come from the registry, so seamless templates list is the authoritative list.
--oauth selects the React OAuth example and then prompts for OAuth providers (Google, GitHub,
Microsoft, GitLab), wires the ones you configure into the auth server, and prints the redirect URI
to register: http://localhost:5173/oauth/callback. See
CLI Init Flow for the full behavior and the template table.
| Environment variable | Effect on init and templates list |
|---|---|
SEAMLESS_TEMPLATES_REF |
Read the published templates repository at this ref instead of the pinned tag |
SEAMLESS_TEMPLATES_DIR |
Read templates from a local checkout instead; takes precedence over the ref |
Non-interactive flags
Section titled “Non-interactive flags”seamless init my-app --local --yes --email=you@example.comseamless init my-app --local --yes --email=you@example.com --api=fastify --admin=noneFlags answer the questions init would otherwise ask, and a question answered by a flag is
skipped. --yes answers the rest with the recommended option, so init can run in CI, a
Dockerfile, or a script. Valued flags take either --flag=value or --flag value.
| Flag | Accepted values | Default | Effect |
|---|---|---|---|
--yes, -y |
none | off | Answer every question no flag answers with the recommended option |
--local |
none | off | Scaffold the self-hosted stack without contacting the control plane |
--app |
a managed application id or infra id | none | Connect to that managed application (needs seamless login) |
--web |
a web or full-stack template id or alias | the first selectable web template in the registry (react-vite) |
Choose the web starter; a full-stack template (nextjs) leaves no api layer |
--api |
an api template id or alias | the first selectable api template in the registry (express) |
Choose the backend starter; refused alongside a full-stack web template |
--mobile |
a mobile template id or alias (expo, mobile) |
none | Add a mobile starter at mobile/; --yes never adds one on its own |
--email |
an email address | your portal session email, when signed in | Owner address, which becomes the admin when you register; required under --yes without a portal session |
--auth |
docker, local |
docker |
Run the auth server as a Docker image or from local source |
--admin |
api, image, source, none |
api |
Where the admin console is hosted; a full-stack web template accepts api or none (only none before 0.20.0) |
--force |
none | off | Under --yes, allow scaffolding into a non-empty directory and rotating an existing managed service token |
--profile |
any | none | Accepted and ignored, with a warning; managed connect uses your portal session |
The template defaults are the first selectable entries of each kind in the registry at the pinned
tag. --web, --api, and --mobile take the same ids and aliases as the bare template flags, and
naming one layer twice with different templates is an error. A bare --mobile with no value
selects Expo (its mobile alias, seamless-cli 0.20.0 and later); a bare --web or --api is an
error. Every flag is validated before a
directory is created.
--yes will not make three decisions on its own:
- Managed or local. If you are signed in to the portal and have an application to connect,
pass
--app <id>or--local. If the control plane cannot be reached,--yesfails rather than falling back to a local stack; pass--local. - Destructive steps. Scaffolding into a directory that is not empty and rotating a managed
application’s existing service token both need
--forceas well. - OAuth providers. The
--oauthstarter is scaffolded with no providers configured. Add them later withseamless config oauth-providers add.
Without a terminal attached and without --yes, any question no flag answers fails with an error
that names the flag to pass, instead of waiting for input. See CLI Init Flow
for the interactive walkthrough.
No shortcut
Section titled “No shortcut”Scaffolding always goes through init. A bare project name such as seamless my-app is rejected as
an unknown command, and the CLI suggests seamless init my-app.
Managed init
Section titled “Managed init”When you are signed in to the portal (seamless login) and your account has a provisioned
application, init offers to connect the new project to it instead of scaffolding a local auth
server.
--app <id>selects the application and skips the question. It fails rather than falling back to local when you are not signed in.--localforces the self-hosted stack without contacting the control plane.initissues the application’s service token and writes it, the managed auth server URL, and theJWKS_KIDinto the.envof the project that serves/auth:api/.envfor an api template, orweb/.envfor a full-stack web template (nextjs), which has no api layer. Issuing a token invalidates any earlier one, soinitasks first.- The Express and Fastify starters also get
DATABASE_URLinapi/.env, pointing at the application’s managed database withUSER:PASSWORDplaceholders for you to fill in from the dashboard. It is left empty, with a warning, while the database is still provisioning. - Connecting a directory that is not empty (chosen at the prompt, or implied by
--app) copies no starters and writes the same values into an existingapi/.env, keeping any keys already there (an existingDATABASE_URLis never overwritten). Without anapi/directory,initprints the values to set by hand. - No local auth server, Docker Compose file, or admin dashboard is generated.
See the Managed Quickstart.
seamless add [path] [--local | --app <id>] [--email=<address>] [--api-url=<url>] [--web-url=<url>] [--admin=<api|none>] [--skip-install] [--yes] [--force]Adds Seamless Auth to an existing project, in the current directory or at path. Shipped in
seamless-cli 0.22.0. It never edits your source files: it writes environment files, installs
packages, and prints the code for you to add. For a walkthrough per backend, see
Add Seamless Auth To An Existing App.
What it does:
- finds a backend and a web app from their manifests, at the project root or in
api/,server/,backend/,web/,client/,frontend/,app/,apps/*, orpackages/*(the first match of each kind wins) - connects an auth server:
--localwrites one toseamless/,--appconnects a managed application, and without either it asks - writes the backend’s
.envand the web app’s API URL in.env.local, keeping every value and comment already there - installs the server adapter and the web binding with the project’s own tool
- prints numbered next steps: install commands it did not run, how to start a local auth server, the code for the backend’s entry file, the code for each web app file, and how to sign in
| Backend | Detected from | Installs |
|---|---|---|
| Express | express in package.json |
@seamless-auth/express, cookie-parser, cors (plus @types/cookie-parser and @types/cors as dev dependencies in a TypeScript project) |
| Fastify | fastify in package.json |
@seamless-auth/fastify, @fastify/cors |
| Go (net/http, Gin, chi, Echo) | go.mod; the framework from its require lines |
go get github.com/fells-code/seamless-auth-go@latest |
| Axum | axum in Cargo.toml |
cargo add seamless-auth, cargo add tower-http --features cors |
| FastAPI, Django | pyproject.toml or requirements.txt |
seamless-auth[fastapi]>=0.2 or seamless-auth[django]>=0.2, plus python-dotenv (and django-cors-headers for Django), with uv add (a uv.lock) or poetry add (a poetry.lock or [tool.poetry]); a plain pip project gets the pip install printed, not run |
Node projects install with npm, pnpm, yarn, or bun, picked from the nearest lock file. A Node
project counts as TypeScript when it has a tsconfig.json or depends on typescript, and the
printed code matches.
| Web app | Detected from | Installs | API URL written |
|---|---|---|---|
| React | react in package.json (not Next.js or React Native) |
@seamless-auth/react, plus react-router-dom if missing |
VITE_API_URL in .env.local, or REACT_APP_API_URL for Create React App |
| Angular | @angular/core |
@seamless-auth/angular, plus @angular/router if missing |
None; the URL is in the printed config, since the Angular CLI does not read .env |
| Vue | vue (not Nuxt) |
@seamless-auth/vue, plus vue-router if missing |
VITE_API_URL in .env.local |
| SvelteKit | @sveltejs/kit |
@seamless-auth/svelte |
VITE_API_URL in .env.local |
A web app is optional. Next.js, Nuxt, Svelte without SvelteKit, Rust without Axum, and Python
without FastAPI or Django are reported as found but not wired. A project with no backend add
can wire, such as a Next.js app on its own, fails with Found no backend to add Seamless Auth to
and exits 1. For Next.js, follow Next.js by hand.
The backend’s .env gets:
| Key | Written | Value |
|---|---|---|
AUTH_SERVER_URL |
Always (replaced if different) | http://localhost:5312 with --local, or the managed instance URL |
AUTH_SERVER_ISSUER |
Always (replaced if different) | http://auth:5312 with --local, or the managed instance URL |
API_SERVICE_TOKEN |
Always (replaced if different) | The local stack’s service token, or a token issued for the managed application |
JWKS_KID |
Always (replaced if different) | The local stack’s key id (dev-main), or the managed instance’s active key id |
COOKIE_SIGNING_KEY |
Only when missing | A generated secret |
UI_ORIGINS |
Only when missing | The web origin |
SERVE_ADMIN_CONSOLE |
Only when missing | true with --local and --admin=api, otherwise false |
New keys are appended under a # Seamless Auth comment. add warns when the .env does not look
gitignored.
| Flag | Accepted values | Default | Effect |
|---|---|---|---|
--local |
none | off | Write a local auth server to seamless/; refused together with --app |
--app |
a managed application id | none | Connect that managed application (needs seamless login) |
--email |
an email address | your portal session email, when signed in | With --local, the owner address that becomes the admin when you register; required under --yes without a portal session |
--api-url |
a URL | http://localhost:<port>: PORT from the backend’s .env, else the entry file’s listen port, else 3000 (Node), 8000 (FastAPI, Django), or 8080 (Go, Rust) |
The backend’s origin: the web app’s API URL, and the auth server’s APP_ORIGINS |
--web-url |
a URL | http://localhost:5173; 4200 for Angular, 3001 for Create React App |
The web app’s origin: UI_ORIGINS, and the auth server’s ORIGINS |
--admin |
api, none |
api |
Whether the backend serves the admin dashboard at /console; none leaves the console lines out |
--skip-install |
none | off | Print the install commands instead of running them |
--yes, -y |
none | off | Answer every question with its default; needs --local or --app |
--force |
none | off | Replace an existing seamless/ stack, or rotate a managed application’s existing service token, without asking |
Valued flags take either --flag=value or --flag value. Any other flag is refused with
Unknown option for seamless add.
--local
Section titled “--local”Writes three files to seamless/ and nothing else at the repository root:
seamless/docker-compose.yml: Postgres and the auth API image the CLI pins, with the auth server published on127.0.0.1:5312only and Postgres not published. It setsname: <repo>-seamless, derived from the repository folder, so the volumes are<repo>-seamless_pgdataand<repo>-seamless_auth-keysand no two repositories share a stack. Start it withdocker compose -f seamless/docker-compose.yml up -d.seamless/.env: the auth server’s configuration and secrets, includingOWNER_EMAIL,ORIGINS(the web origin, plus the backend origin when the console is served), andAPP_ORIGINS(the backend origin).seamless/.gitignore: ignoresseamless/.env.
When seamless/docker-compose.yml already exists, add asks before replacing it, because a new
stack issues new secrets. Under --yes it fails instead unless you also pass --force. A
replaced file keeps its existing name:. Replacing a file from seamless-cli 0.23.0 or earlier,
which had no name:, prints the command to stop the old seamless project first.
Connects a managed application. It needs a portal session (seamless login), and only applications
whose auth server has finished provisioning are offered. Issuing a service token invalidates the
application’s existing one, so add asks first; under --yes it fails unless you also pass
--force. Nothing is written to seamless/, and the printed code leaves out the console lines.
Without a terminal
Section titled “Without a terminal”Without --local or --app, add asks which auth server to use. With no terminal attached it
fails and names the flags to pass, and --yes without either fails the same way, so it is safe in
scripts and agents:
seamless add --local --yes --email=you@example.com < /dev/nulltemplates
Section titled “templates”seamless templates list [--json]seamless templatesLists the starters init can scaffold, read from the same registry init uses, so
SEAMLESS_TEMPLATES_REF and SEAMLESS_TEMPLATES_DIR apply here too. It needs no login. list is
the only subcommand, and a bare seamless templates runs it.
The table shows each template’s id, kind (web, fullstack, api, or mobile), framework, the
init flags that select it (--<id>, plus --<alias> when it declares one), and status. A
coming-soon template cannot be selected yet, so it lists no flag.
| Flag | Effect |
|---|---|
--json |
Print the registry entries as a JSON array, for scripting |
seamless check [--strict]Use this when you want to validate a generated project. Run it from the project root, where
seamless.config.json lives.
Every check runs, so one failure does not hide the rest. It checks:
seamless.config.jsonexists and is valid JSON- the configured web path, the API path (or, for a full-stack web template, that the web app serves the backend), and the mobile path when the project has one
For a local (Docker or source) project it then checks:
- Docker availability
docker-compose.yml- that the backend container is running (
api, orwebfor a full-stack project) - the health endpoints below
| Probe | URL | When |
|---|---|---|
| API | http://localhost:3000/ |
The project has an api layer |
| Web | http://localhost:5173/health |
Full-stack project, where the web app serves /auth |
| Auth | http://localhost:5312/health/status |
Always |
| Console | http://localhost:3000/console |
Admin mode api; services.admin.url in the config, if set, replaces this URL |
| Console | http://localhost:5173/console |
Admin mode api with a full-stack template (seamless-cli 0.20.0 or later) |
| Console | http://localhost:5174 |
Admin mode image or source |
Admin mode none has no console to probe. For a managed project, check skips the Docker, Compose,
and container checks and instead probes <instance-url>/health/status on the managed auth server
recorded in seamless.config.json.
| Flag | Effect |
|---|---|
--strict |
Exit 1 when any check failed, for a health-check script or CI gate. Without it, check exits 0 |
It does not currently check Terraform, AWS CLI, or deployment state.
owner-code
Section titled “owner-code”seamless owner-code [email] [--url <auth-url>] [--json]Available in seamless-cli 0.24.0 or later. Prints a one-time email code for the owner of a local stack, so the first admin can finish registering without reading container logs. Register in the web app with the owner address first, then run this from the project root when the page asks for a code.
It waits for the auth server to answer /health/status, then registers the address with external
delivery, which the scaffolded stack allows in development, and prints the code from the response.
The auth server keeps one email code per account, so the printed code replaces the one the page
sent and works on that page. Each code expires after 5 minutes.
| Argument or flag | Effect |
|---|---|
[email] |
The address to issue a code for. Defaults to OWNER_EMAIL from auth/.env or the compose file |
--url <auth-url> |
The auth server, default http://localhost:5312. Only a local address is accepted |
--json |
Print { "email", "code" } as JSON |
verify
Section titled “verify”seamless verifyRuns a cross-package auth conformance harness. It stands up the ecosystem with Docker Compose (Postgres, the auth API, an Express adapter app and a Fastify adapter app, and each web template in turn), then runs a Playwright matrix across the api, adapter, and react layers and prints a flow x layer pass/fail grid alongside JUnit and HTML reports.
- api verifies the auth API directly (Bearer / JSON).
- adapter verifies the cookie path through both adopter frameworks, with the same specs run
twice: once against
@seamless-auth/expressand once against@seamless-auth/fastify. Each framework gets its own row in the grid, so a regression in one shows up on its own. - react drives every runnable (not
coming-soon) web template in the registry, one at a time, in a real browser (Chromium), including passkeys via a virtual authenticator and OAuth via an in-process mock OIDC provider. Mobile templates (expo) and full-stack templates (nextjs) are skipped with a printed notice: the harness cannot drive a native app, and cannot yet run a template that serves its own/auth.
Covered flows include register, email and phone OTP, magic-link, passkey register and login, OAuth, TOTP, step-up, refresh, sessions, logout, organizations, the owner admin grant, and JWKS.
Modes and flags
Section titled “Modes and flags”seamless verify # test the published @seamless-auth/* packagesseamless verify --local # build the SDKs from local source (pre-publish contract test)| Flag | Effect |
|---|---|
--local |
Build @seamless-auth/* (core, express, fastify, and react when the browser layer runs) from local source instead of published |
--api-only |
Run only the api project (skip both adapters and react) |
--no-react |
Skip the browser layer |
--filter=<flow> |
Run only tests matching <flow> (passed to Playwright as --grep), in every layer. The space form --filter <flow> is not parsed |
--keep-up |
Leave the Docker stack running after the run |
Without --filter, each web template runs only the flows its template.json lists under
verify.flows, or every flow when it lists none. --filter replaces that per-template scope.
| Adapter | Package under test | Compose service | URL the harness calls |
|---|---|---|---|
| Express | @seamless-auth/express |
adapter |
http://localhost:3000 (SEAMLESS_ADAPTER_URL) |
| Fastify | @seamless-auth/fastify |
adapter-fastify |
http://localhost:3001 (SEAMLESS_FASTIFY_ADAPTER_URL) |
verify sets both URLs for the harness itself, so they are listed to explain the grid, not as
settings. Without --local, each adapter app installs the version its package.json pins, and the
end-of-run summary lists the package versions that were tested.
Requires Docker. The sibling repos are resolved relative to the CLI checkout and can be overridden:
| Environment variable | Overrides |
|---|---|
SEAMLESS_API_DIR |
The seamless-auth-api checkout the auth server is built from |
SEAMLESS_SERVER_DIR |
The seamless-auth-server checkout (needed for --local) |
SEAMLESS_REACT_SDK_DIR |
The seamless-auth-js checkout (needed for --local browser runs) |
SEAMLESS_TEMPLATES_DIR |
The seamless-templates checkout; every runnable web template in its registry.json is driven |
SEAMLESS_REACT_DIR |
A single template directory to drive instead of the whole registry |
The stack runs with fixed development values, which these environment variables override:
| Environment variable | Default | Used as |
|---|---|---|
API_SERVICE_TOKEN |
verify-dev-service-token-not-a-real-secret |
The service token shared by the auth API and the adapter apps |
OWNER_EMAIL |
owner@verify.local |
The owner address; the harness registers it and asserts the admin grant |
JWKS_KID |
dev-main |
kid header on the adapters’ service tokens; the auth API does not check it |
The adapters reuse the service token as their cookie signing key, which @seamless-auth/express
requires to be at least 32 characters, so keep an override at that length or longer.
SEAMLESS_VERIFY_COMPOSE_OVERRIDE names an extra Compose file that verify layers over its base
verify/docker-compose.verify.yml, passed as a second -f on every docker compose call it makes
(build, up, logs, and teardown). It is unset by default, and a local run needs nothing from it. CI
points it at verify/docker-compose.cache.yml, which attaches a GitHub Actions build cache to each
image. A relative path resolves from the CLI’s verify/ directory, so an absolute path is safer.
verify always reads templates from a local checkout, so SEAMLESS_TEMPLATES_REF (which selects a
ref of the published repository for init) has no effect here. A reusable GitHub workflow runs
seamless verify --local on ecosystem PRs so a change in one repo is tested against the others.
profile
Section titled “profile”Profiles are named pointers to the Seamless Auth instances the CLI targets. They are stored in
~/.config/seamless/config.json (respects XDG_CONFIG_HOME). The file holds only non-secret instance
and identity metadata, never tokens.
seamless profile listseamless profile add <name> --instance-url <url> [--identifier-type email|phone] [--oidc-issuer <url> --client-id <id>]seamless profile use <name>seamless profile remove <name>seamless profile login [name] [identifier] [--identifier <email>] [--local] [--device] [--email-code] [--oidc-issuer <url>] [--client-id <id>]listshows configured profiles; the active one is marked with*.addcreates or updates a profile and prompts interactively if flags are omitted. Non-local URLs must behttps.usesets the active profile for later commands.removedeletes a profile and clears its keychain tokens.loginsigns in to that instance sousers,config,org,sessions, andmigratecan run. It defaults to the active profile and does not change which profile is active.--localreads the OTP from the instance response, as onlogin, and only works against a local instance URL.
Choose the active profile per command with --profile <name> or the SEAMLESS_PROFILE environment
variable.
Signing in through the OpenID Provider
Section titled “Signing in through the OpenID Provider”When the profile has a provider, profile login signs in through it and exchanges the sign-in at
POST /sessions/exchange for a first-party session. It stores that session in the OS keychain and
keeps no token from the provider. It checks the keychain before it starts, and fails early on a
machine with none.
| Flag | What it does |
|---|---|
| (none) | Opens the system browser, with a loopback redirect on 127.0.0.1, a random port and PKCE S256. BROWSER overrides the browser. |
--device |
Uses the device grant: prints a URL and a code to approve on any device. For a machine with no browser. Cannot be combined with --email-code or --local. With no provider, it falls back to an email code and says so. |
--email-code |
Signs in with an email code on purpose, even when a provider is known. |
--oidc-issuer <url> |
Names the provider’s issuer, which must be https. Needs --client-id too. Saved to the profile on a successful sign-in. |
--client-id <id> |
Names the client the CLI signs in with. Saved to the profile on a successful sign-in. |
- Which provider. Flags win over what the profile saved, which wins over
oidcProvideronGET /system-config/public. With no provider from any of them,profile loginuses an email code. An issuer that is known but cannot be read stops the sign-in rather than falling back. - The advertisement. It is read only over https or on loopback, so an instance on plain http
needs the flags. An advertised issuer on another origin needs your confirmation, and without a
terminal the CLI stops and asks for the flags.
oidc_cli_client_idis not settable throughseamless configyet (seamless-cli#351). - A failed exchange. Sign in again. The CLI never retries one: the token works once, and a replay revokes the session the first attempt created.
- A session from
--devicemust step up with the authenticator app before admin and organization commands, reads included.whoami,logoutandsessionsneed none. A browser session can step up with a passkey as well.
The client has to exist first. See clients for how to register it. The guide has the
reasoning: Signing In To Seamless With The Seamless
CLI.
clients
Section titled “clients”seamless clients create <name> [--public] [flags]seamless clients update <id> [flags]Registers and changes the OIDC clients on an instance. It needs an admin role, and writes need a fresh step-up. Use Seamless Auth As An OpenID Provider covers the other subcommands and flags.
--session-exchange and --no-session-exchange turn session exchange on and off for a first-party
public native client, which is what lets that client sign in the CLI with
profile login. clients get shows the setting. Turning it
off revokes the sessions the client exchanged for, including the one running the command if it signed
in through that client. These flags are in seamless-cli 0.30.0 and later, and need Seamless Auth
API v0.23.0 or later.
seamless clients create "Seamless CLI" --public --first-party --auth-method none \ --redirect-uri http://127.0.0.1/callback --device-flow --session-exchange
seamless clients update <id> --session-exchangeseamless clients update <id> --no-session-exchangeThe loopback redirect is required even if you will only use --device. --device-flow is needed only
for --device.
seamless login [identifier] [--identifier <email>] [--local]Signs in to the Seamless portal, the managed control plane. This is the account that authorizes
listing managed applications and connecting a project to one, and it needs no profile. Prompts for
the identifier (or pass it positionally or with --identifier) and the emailed code, then stores the
session in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
To sign in to an auth instance you administer, use seamless profile login instead. The two are
separate accounts even when they share an email address.
--local is for developing against a local portal only: the instance returns the OTP in its
response instead of emailing it, and the CLI verifies with it automatically. It needs
SEAMLESS_PORTAL_AUTH_URL pointed at a local instance running outside production with
ALLOW_UNCREDENTIALED_DELIVERY_SECRETS=true. login --profile <name> still works but is
deprecated; it prints a warning and runs seamless profile login <name>.
seamless apps list [--json]seamless apps get <id|name|infra-id> [--json]Shows the managed applications your portal account owns. Requires seamless login, not an instance
profile. A bare seamless apps lists. apps get reports whether a service token has been issued,
masked, never the live value.
whoami
Section titled “whoami”seamless whoami [--profile <name>] [--json]Shows the identity behind your portal session (sub, email, roles), along with the account and
instance URL. With no portal session it falls back to the active instance profile, and
--profile <name> reports that instance session instead. Exits 1 if you are not logged in.
| Flag | Effect |
|---|---|
--profile <name> |
Report the session for that instance profile instead of the portal |
--json |
Print account, instanceUrl, sub, email, and roles as JSON, with a missing sub or email as null |
logout
Section titled “logout”seamless logout [--all] [--profile <name>]Ends your portal session and clears the local keychain tokens. Like whoami, it falls back to the
active instance profile when there is no portal session, and --profile <name> logs out of that
instance instead. --all revokes every session for the user before clearing local tokens.
sessions
Section titled “sessions”seamless sessions [list] [--json]seamless sessions revoke <id> [--force]seamless sessions revoke --all [--force]Lists active sessions for the logged-in user (session id, device or user agent, IP, and last-used
time, with the current session marked) and revokes them. A bare seamless sessions lists. Revoking
the current session or --all prompts for confirmation and then clears local tokens.
| Flag | Effect |
|---|---|
--json |
On list, print the sessions as JSON instead of the table |
--force |
On revoke, skip the confirmation (--yes and -y are aliases), which also lets it run without a terminal |
--profile <name> |
Act on that instance profile instead of the active one |
config
Section titled “config”Read and write the instance system configuration. Requires an admin role on the target instance.
Against auth API v0.20 and later, every admin write (config set and apply, the
oauth-providers writes, users delete and prepare-device-replacement, the org and
org members writes, and each migrate batch) needs a fresh step-up. From CLI 0.26.0, when the
instance answers 403 step_up_required, the CLI asks for a code from the admin account’s
authenticator app, verifies it on the same session, and retries once. Without a terminal,
SEAMLESS_TOTP_CODE supplies the code for the first step-up of a run. An account with no
authenticator app enrolled cannot step up from the CLI.
seamless config get [key] [--json]seamless config set <key> <value>seamless config roles [--json]seamless config diff <file>seamless config apply <file> [--dry-run] [--force]seamless config oauth-providers list [--json]seamless config oauth-providers add (<json> | --file <path>)seamless config oauth-providers update <id> (<json> | --file <path>)seamless config oauth-providers remove <id> [--force]getprints the whole config, or one key.roleslists the instance’s available roles.setupdates one writable key. The string-typed keys (app_name,rpid,access_token_ttl,session_idle_ttl,refresh_token_ttl) take the value verbatim, soconfig set app_name 123sets the string"123". Every other key parses the value as JSON, falling back to a string (for exampleseamless config set login_methods '["email_otp","passkey"]').diffshows how a local JSON config file differs from the instance.applywrites a local JSON config file after a confirmation prompt, ignoring read-only and unknown keys.--dry-runprints the changes and writes nothing.
config oauth-providers (alias config oauth) manages OAuth providers one at a time through the
/system-config/oauth-providers routes, without rewriting the whole oauth_providers key. A
provider is a JSON object, passed inline or with --file, in the shape described under
OAuth Providers. Client secrets stay server-side,
referenced by clientSecretEnv; the secret value is never sent.
listshows each provider’s id, name, and whether it is enabled.addcreates a provider.updatechanges the provider named by<id>. The id comes from the argument, and anidin the body is dropped.remove(aliasdelete) asks for confirmation, then deletes the provider.
seamless config oauth-providers add --file google.jsonseamless config oauth-providers update google '{"enabled":false}'seamless config oauth-providers remove google --force| Flag | Effect |
|---|---|
--json |
On get, roles, and oauth-providers list, print JSON |
--dry-run |
On apply, show the changes without writing them |
--force |
Skip the confirmation on apply and oauth-providers remove (--yes and -y are aliases), which also lets them run without a terminal |
--file <path> |
On oauth-providers add and update, read the provider JSON from a file |
--profile <name> |
Act on that instance profile instead of the active one |
Admin user management. Requires an admin role.
seamless users list [--limit <n>] [--offset <n>] [--json]seamless users delete <id> [--force]seamless users credentials <id> [--json]seamless users prepare-device-replacement <id> --proofing <in_person|remote_exception> --evidence-ref <ref> [--approver <name>] [--force] [--keep-sessions] [--keep-passkeys] [--keep-totp]list shows 50 users at a time by default. --limit takes 1 to 100 and --offset 0 or more, and
the total it prints counts every user, not just the page shown. delete asks for confirmation.
prepare-device-replacement is admin-assisted account recovery and needs an elevated (stepped-up)
session. By default it revokes the user’s sessions, removes their passkeys, and disables TOTP, after
a confirmation; each --keep-* flag leaves that one in place. From CLI 0.26.0 it requires
--proofing (in_person when you verified the user face to face, remote_exception when you did
it remotely under an approved exception) and --evidence-ref, a ticket or case number of up to 200
characters that is written to the audit trail, so keep personal data out of it. --approver is
optional.
--force skips the confirmation on delete and prepare-device-replacement (--yes and -y are
aliases), which also lets them run without a terminal. --profile <name> targets another instance.
Admin organization and membership management. Requires an admin role.
seamless org list [--limit <n>] [--offset <n>] [--search <text>] [--json]seamless org create <name> [--slug <slug>]seamless org get <id> [--json]seamless org update <id> [--name <name>] [--slug <slug>]seamless org members list <orgId> [--json]seamless org members add <orgId> (--user <id> | --email <email>) [--roles a,b] [--scopes a,b]seamless org members update <orgId> <userId> [--roles a,b] [--scopes a,b]seamless org members remove <orgId> <userId> [--force]list shows 50 organizations at a time by default; --limit takes 1 to 100 and --offset 0 or
more. --search matches the name and slug, and the total counts every match rather than the page
shown. create also takes the name as --name <name>. members remove asks for confirmation, and
--force skips it (--yes and -y are aliases), which also lets it run without a terminal.
--profile <name> targets another instance.
migrate
Section titled “migrate”seamless migrate csv <file> [--map <mapping.json>] [--source <name>] [--apply] [--report <path>] [--json]seamless migrate entra-id [--group <id>] [--groups <mapping.json>] [--allow-upn] [--include-guests] [--source <name>] [--apply] [--report <path>] [--json]seamless migrate auth0 <export.ndjson> [--map <mapping.json>] [--allow-unverified] [--source <name>] [--apply] [--report <path>] [--json]seamless migrate cognito <list-users.json>... [--groups <groups.json>] [--map <mapping.json>] [--allow-unverified] [--include-unconfirmed] [--source <name>] [--apply] [--report <path>] [--json]seamless migrate assess <csv|entra-id|auth0|cognito> [source args] [--report <path>] [--json]Imports users from another identity system into the instance. Requires an admin role, signed in
with seamless profile login. There are four sources: csv (any system’s CSV export, described
first below), entra-id (CLI 0.25.0), and auth0 and cognito (CLI 0.27.0). Every source runs as
a dry run unless you pass --apply, and writes a report either way. migrate assess (CLI 0.27.0)
reads any source without an instance.
What it does:
- finds the columns by header name, or takes them from a mapping file
- validates each row locally; a row that fails is reported as
invalidand never sent - sends the valid rows to
POST /admin/users/importin batches of 200, withdryRunset unless--applyis passed, so a dry run is still checked by the instance - prints a summary (created, updated, unchanged, rejected, invalid) and the first problem rows
- writes the full per-row report as
<path>.csvand<path>.json - exits 1 when any row is rejected or invalid
Without a mapping file, headers are matched case-insensitively, ignoring spaces, underscores, and hyphens:
| Field | Recognized headers | Notes |
|---|---|---|
email |
email, email address, work email, mail |
Required |
externalId |
externalId, id, employee id, user id |
Matches people on re-runs from the same source |
phone |
phone, phone number, mobile, mobile phone |
|
roles |
roles, role |
Multi-value |
organizations |
organizations, organization, department, departments |
Multi-value; each a slug or an organization id, which must exist |
Multi-value cells are split on ;, or the mapping’s separator. Any other column, including a password column, is not read.
| Flag | Default | Effect |
|---|---|---|
--map <mapping.json> |
none | Name the columns and defaults yourself (see below) |
--source <name> |
the mapping’s source, or csv |
The system the users come from: lowercase letters, digits, and hyphens. Keep it stable across re-runs |
--apply |
off | Write to the instance. Without it nothing is written |
--report <path> |
next to the input | Write <path>.csv and <path>.json. By default users.csv gets users.migrate-plan.* on a dry run and users.migrate-result.* with --apply |
--json |
off | Print the report as JSON instead of the summary |
--profile <name> |
the active profile | Import into that instance profile |
A mapping file sets the source, the header for each field, the separator, roles added to every row,
and the membership roles given for each organization a row names (the server defaults to member):
{ "source": "hr-export", "columns": { "email": "Work Email", "externalId": "Employee ID" }, "separator": "|", "roles": ["staff"], "organizationRoles": ["member"]}columns accepts only email, externalId, phone, roles, and organizations. Any other key,
such as password, is refused with Unknown mapping column, and so is a header the CSV does not
have.
Imports carry no passwords or other credentials. Each imported user signs in for the first time by
registering with their email. Roles and memberships are only added, never removed, so re-running an
import after correcting the source data cannot take access away. The instance rejects a row that
grants an admin role, or that would link an external id to an existing account holding one
(admin_role_not_allowed), and reports other rejections such as role_unavailable,
organization_not_found, duplicate_in_batch, and external_id_conflict per row. An auth server
without the import route fails with a message to upgrade it.
migrate assess
Section titled “migrate assess”seamless migrate assess auth0 auth0-users.json --map auth0-map.jsonseamless migrate assess cognito cognito-users.json --groups cognito-groups.jsonseamless migrate assess csv users.csvWrites a readiness report from the source alone. It needs no Seamless Auth instance and no login,
and sends nothing to one (entra-id still reads Microsoft Graph). It takes any source and that
source’s arguments, and reuses its parsing and validation. The report covers:
- users found, how many would import, and the reasons the rest would not, including users who share an email
- contact coverage: verified email, an email the source marks unverified, an email with no verification recorded, phone only, and neither
- the roles and organization memberships the import would grant, and the export fields it leaves behind
- features of the source that Seamless Auth does not cover, seen in the export or not visible in one, linked to the matching guide’s “What You Give Up” section
- a link to the Identity Cost Calculator with the user count filled in
| Flag | Default | Effect |
|---|---|---|
--report <path> |
<input>.migrate-assess.md beside the input, or <source>.migrate-assess.md in the current directory |
Write the Markdown report to <path>.md |
--json |
off | Print the assessment as JSON instead of the summary |
The Markdown holds counts and the names of fields, roles, and organizations, never a user’s email,
phone, or id. Roles and organizations are only checked against the instance by a dry run, so the
dry run can still reject rows the assessment passed. assess refuses --apply and exits 0.
migrate entra-id
Section titled “migrate entra-id”Reads users straight from Microsoft Entra ID through Microsoft Graph, signed in as an app
registration with the application permissions User.Read.All, and GroupMember.Read.All for
--group or --groups, with admin consent. The tenant id, client id, and secret come from
ENTRA_TENANT_ID, ENTRA_CLIENT_ID, and ENTRA_CLIENT_SECRET, never flags. The object id is the
externalId, mail the email, and mobilePhone the phone.
| Flag | Effect |
|---|---|
--group <id> |
Import only that group’s members, nested groups included |
--groups <mapping.json> |
Turn group membership into organizations and roles: { "groups": [{ "id": "<group id>", "organization": "engineering", "roles": ["staff"] }] } |
--allow-upn |
Use userPrincipalName for a user with no mail. A UPN is not always a mailbox |
--include-guests |
Import guest accounts too |
--source <name> |
Default entra-id |
Disabled accounts and guests are reported as skipped. The report defaults to
entra-id.migrate-plan (or entra-id.migrate-result) in the current directory.
migrate auth0
Section titled “migrate auth0”Reads the NDJSON an Auth0 user export job writes, one user per line, gzip-compressed or not (a JSON array of users is read too). It reads the file only and needs no Auth0 credentials.
| Auth0 field | Import |
|---|---|
user_id |
externalId |
email |
email. A user with none is invalid |
email_verified |
false is skipped, unless --allow-unverified |
phone_number |
phone |
blocked |
true is skipped |
| metadata | Only through --map |
| Flag | Default | Effect |
|---|---|---|
--map <mapping.json> |
none | Read roles and organizations from metadata: { "columns": { "roles": "app_metadata.roles", "organizations": "app_metadata.org" } }. Paths start with app_metadata or user_metadata. roles, organizationRoles, separator, and source work as for csv |
--allow-unverified |
off | Import users whose email Auth0 never verified. Whoever registers with that address first gets the account |
--source <name> |
auth0 |
Keep it the same as the cutover provider’s externalIdSource |
Report rows are numbered by the line of the export. See Migrating Off Auth0.
migrate cognito
Section titled “migrate cognito”Reads aws cognito-idp list-users output: one response, the Users array, an array of responses,
responses concatenated, or several files (one per exported chunk) in the order given. It reads files
only and needs no AWS credentials.
| Cognito field | Import |
|---|---|
sub attribute |
externalId |
email attribute |
email. A user with none is invalid |
email_verified attribute |
"false" is skipped, unless --allow-unverified |
phone_number attribute |
phone |
Enabled |
false is skipped |
UserStatus |
UNCONFIRMED is skipped, unless --include-unconfirmed |
| Flag | Default | Effect |
|---|---|---|
--groups <groups.json> |
none | Turn groups into roles, from a map of username to group names: { "ada": ["staff"] }. Cognito’s <pool id>_<provider> groups are ignored |
--map <mapping.json> |
none | Read roles or organizations from an attribute: { "columns": { "organizations": "custom:tenant" } } |
--allow-unverified |
off | Import users whose email_verified is "false" |
--include-unconfirmed |
off | Import users who never confirmed their sign-up |
--source <name> |
cognito |
Keep it the same as the cutover provider’s externalIdSource |
With several input files the report defaults to cognito.migrate-plan in the current directory.
See Migrating Off Amazon Cognito.
For the whole migration, from assessing the source to getting users onto passkeys, see Migrate Users From Another Identity System.
Removed Or Not Currently Shipped
Section titled “Removed Or Not Currently Shipped”The current ../seamless-cli source does not include these commands:
seamless deployseamless destroyseamless contributeseamless bootstrap-admin(replaced by the owner email asked for duringinit)
Help And Version
Section titled “Help And Version”If no command is provided, the CLI prints help.
seamless --helpseamless help [command]seamless <command> --helpseamless --version-h and -v are short forms of --help and --version. seamless help <command> and
seamless <command> --help (or -h) print that one command’s usage, ahead of any argument parsing,
so they work without a login or a project. A --help after a literal -- is passed through as an
argument instead. An unknown command exits 1 and lists the valid ones.