Skip to content

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

Terminal window
npx seamless-cli init my-app
npx seamless-cli check

Terminal window
seamless init my-app

If you omit the project name:

Terminal window
seamless init

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

  • 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=expo to 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 /console or 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.

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
Terminal window
seamless init my-app --oauth
seamless init my-app --web=nextjs
seamless templates list

Each 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
Terminal window
seamless init my-app --local --yes --email=you@example.com
seamless init my-app --local --yes --email=you@example.com --api=fastify --admin=none

Flags 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, --yes fails 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 --force as well.
  • OAuth providers. The --oauth starter is scaffolded with no providers configured. Add them later with seamless 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.

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.

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.
  • --local forces the self-hosted stack without contacting the control plane.
  • init issues the application’s service token and writes it, the managed auth server URL, and the JWKS_KID into the .env of the project that serves /auth: api/.env for an api template, or web/.env for a full-stack web template (nextjs), which has no api layer. Issuing a token invalidates any earlier one, so init asks first.
  • The Express and Fastify starters also get DATABASE_URL in api/.env, pointing at the application’s managed database with USER:PASSWORD placeholders 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 existing api/.env, keeping any keys already there (an existing DATABASE_URL is never overwritten). Without an api/ directory, init prints the values to set by hand.
  • No local auth server, Docker Compose file, or admin dashboard is generated.

See the Managed Quickstart.


Terminal window
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/*, or packages/* (the first match of each kind wins)
  • connects an auth server: --local writes one to seamless/, --app connects a managed application, and without either it asks
  • writes the backend’s .env and 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.

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 on 127.0.0.1:5312 only and Postgres not published. It sets name: <repo>-seamless, derived from the repository folder, so the volumes are <repo>-seamless_pgdata and <repo>-seamless_auth-keys and no two repositories share a stack. Start it with docker compose -f seamless/docker-compose.yml up -d.
  • seamless/.env: the auth server’s configuration and secrets, including OWNER_EMAIL, ORIGINS (the web origin, plus the backend origin when the console is served), and APP_ORIGINS (the backend origin).
  • seamless/.gitignore: ignores seamless/.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 --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:

Terminal window
seamless add --local --yes --email=you@example.com < /dev/null

Terminal window
seamless templates list [--json]
seamless templates

Lists 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

Terminal window
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.json exists 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, or web for 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.


Terminal window
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

Terminal window
seamless verify

Runs 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/express and 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.

Terminal window
seamless verify # test the published @seamless-auth/* packages
seamless 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.


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.

Terminal window
seamless profile list
seamless 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>]
  • list shows configured profiles; the active one is marked with *.
  • add creates or updates a profile and prompts interactively if flags are omitted. Non-local URLs must be https.
  • use sets the active profile for later commands.
  • remove deletes a profile and clears its keychain tokens.
  • login signs in to that instance so users, config, org, sessions, and migrate can run. It defaults to the active profile and does not change which profile is active. --local reads the OTP from the instance response, as on login, and only works against a local instance URL.

Choose the active profile per command with --profile <name> or the SEAMLESS_PROFILE environment variable.

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 oidcProvider on GET /system-config/public. With no provider from any of them, profile login uses 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_id is not settable through seamless config yet (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 --device must step up with the authenticator app before admin and organization commands, reads included. whoami, logout and sessions need 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.


Terminal window
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.

Terminal window
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-exchange
seamless clients update <id> --no-session-exchange

The loopback redirect is required even if you will only use --device. --device-flow is needed only for --device.


Terminal window
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>.


Terminal window
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.


Terminal window
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

Terminal window
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.


Terminal window
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

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.

Terminal window
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]
  • get prints the whole config, or one key. roles lists the instance’s available roles.
  • set updates one writable key. The string-typed keys (app_name, rpid, access_token_ttl, session_idle_ttl, refresh_token_ttl) take the value verbatim, so config set app_name 123 sets the string "123". Every other key parses the value as JSON, falling back to a string (for example seamless config set login_methods '["email_otp","passkey"]').
  • diff shows how a local JSON config file differs from the instance.
  • apply writes a local JSON config file after a confirmation prompt, ignoring read-only and unknown keys. --dry-run prints 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.

  • list shows each provider’s id, name, and whether it is enabled.
  • add creates a provider.
  • update changes the provider named by <id>. The id comes from the argument, and an id in the body is dropped.
  • remove (alias delete) asks for confirmation, then deletes the provider.
Terminal window
seamless config oauth-providers add --file google.json
seamless 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.

Terminal window
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.

Terminal window
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.


Terminal window
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 invalid and never sent
  • sends the valid rows to POST /admin/users/import in batches of 200, with dryRun set unless --apply is 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>.csv and <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.

Terminal window
seamless migrate assess auth0 auth0-users.json --map auth0-map.json
seamless migrate assess cognito cognito-users.json --groups cognito-groups.json
seamless migrate assess csv users.csv

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

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.

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.

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.


The current ../seamless-cli source does not include these commands:

  • seamless deploy
  • seamless destroy
  • seamless contribute
  • seamless bootstrap-admin (replaced by the owner email asked for during init)

If no command is provided, the CLI prints help.

Terminal window
seamless --help
seamless help [command]
seamless <command> --help
seamless --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.