CLI Command Reference

CLI Commands

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

Command	Purpose
`seamless init [project-name]`	Scaffold a new self-hosted local Seamless Auth project
`seamless check`	Validate generated project config, Docker, Compose, containers, and local health endpoints
`seamless bootstrap-admin [email]`	Create the first admin bootstrap invite
`seamless verify [flags]`	Run the cross-package auth conformance harness (api / adapter / react matrix)
`seamless profile <sub>`	Manage named pointers to the instances the CLI targets
`seamless login [identifier]`	Log in to the active profile’s instance with email OTP
`seamless whoami`	Show the identity, profile, and instance URL behind the current session
`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 --help`	Print usage
`seamless --version`	Print the installed CLI version

The init, check, bootstrap-admin, and verify commands are for building and testing a self-hosted stack. The profile, login, whoami, logout, sessions, config, users, and org commands act as an authenticated client against a running instance (managed or self-hosted).

Use npx seamless-cli ... when you do not have the package installed globally:

npx seamless-cli init my-app
npx seamless-cli check
npx seamless-cli bootstrap-admin admin@example.com

`init`

seamless init my-app

If you omit the project name:

seamless init

The CLI uses the current directory. If the directory is not empty, the current source prints that an existing project was detected and exits; a full existing-project integration flow is not shipped yet.

What it does

prompts for frontend and backend choices
prompts for an optional mobile app (Expo), or takes --mobile=expo to skip the prompt
prompts for auth mode
optionally includes the admin dashboard
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 run:ios (or run:android). See React Native SDK.

Current generated stack

Today the supported generated path is centered on:

React for the frontend
Express for the backend
Seamless Auth API in Docker or local source mode
optional admin dashboard in image or source mode

Shortcut behavior

This is valid:

seamless my-app

It is treated as:

seamless init my-app

Managed init (planned)

A managed init flow, where seamless init connects a scaffolded app to your hosted managed instance instead of hardwiring localhost. Running seamless init when logged in will default to the managed path, adding --local will force the self-hosted stack. at localhost. Running seamless init while not logged in and in an non-empty directory will print ‘log in first’ and exit. It hardwires the auth URL to http://localhost:5312 and the API URL to http://localhost:3000 and generates tokens locally. It does not read your logged-in profile or connect a scaffolded app to a hosted managed instance.

`check`

seamless check

Use this when you want to validate a generated project.

It checks:

seamless.config.json
configured web and API paths
Docker availability
docker-compose.yml
expected running containers
API health at http://localhost:3000/
auth health at http://localhost:5312/health/status
admin availability at http://localhost:5174

It does not currently check Terraform, AWS CLI, or deployment state.

`bootstrap-admin`

seamless bootstrap-admin admin@example.com

This creates the first admin bootstrap invite.

How it resolves the secret

The CLI attempts to resolve the bootstrap secret automatically from:

.env
auth/.env
docker-compose.yml

If it cannot find the secret automatically, it prompts you for it.

API target

The CLI sends the invite request to:

{SEAMLESS_API_URL or http://localhost:3000}/auth/internal/bootstrap/admin-invite

Set SEAMLESS_API_URL when your generated API is not reachable at http://localhost:3000.

What happens next

After the invite is created:

a registration URL may be printed
the invited user completes registration with the invited email
the resulting account receives admin access

This is for the initial admin bootstrap flow, not general role management.

`verify`

seamless verify

Runs a cross-package auth conformance harness. It stands up the ecosystem with Docker Compose (Postgres, the auth API, the @seamless-auth/express adapter, and the React starter), then runs a Playwright matrix across three 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 @seamless-auth/express cookie path.
react drives the React starter in a real browser (Chromium), including passkeys via a virtual authenticator and OAuth via an in-process mock OIDC provider.

Covered flows include register, email and phone OTP, magic-link, passkey register and login, OAuth, TOTP, step-up, refresh, sessions, logout, organizations, admin bootstrap, and JWKS.

Modes and flags

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/*` from local source instead of published
`--api-only`	Run only the api project (skip adapter and react)
`--no-react`	Skip the browser layer
`--filter <grep>`	Run only tests matching the grep
`--keep-up`	Leave the Docker stack running after the run

Requires Docker. The sibling repos are resolved relative to the CLI checkout and can be overridden with SEAMLESS_API_DIR, SEAMLESS_SERVER_DIR, SEAMLESS_REACT_SDK_DIR (the React SDK), and SEAMLESS_REACT_DIR (the starter app). A reusable GitHub workflow runs seamless verify --local on ecosystem PRs so a change in one repo is tested against the others.

`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 list
seamless profile add <name> --instance-url <url> [--identifier-type email|phone]
seamless profile use <name>
seamless profile remove <name>

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.

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

`login`

seamless login [identifier] [--identifier <email>] [--profile <name>]

Logs in to the active profile’s instance using email OTP. 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). For headless use, SEAMLESS_REFRESH_TOKEN is used directly when set.

`whoami`

seamless whoami [--profile <name>]

Shows the identity behind the active session (sub, email, roles), along with the profile name and instance URL. Fails cleanly if you are not logged in.

`logout`

seamless logout [--all] [--profile <name>]

Ends the current session on the instance and clears the local keychain tokens. --all revokes every session for the user before clearing local tokens.

`sessions`

seamless sessions list
seamless sessions revoke <id>
seamless sessions revoke --all

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. Revoking the current session or --all prompts for confirmation and then clears local tokens.

`config`

Read and write the instance system configuration. Requires an admin role on the target instance.

seamless config get [key] [--json]
seamless config set <key> <value>
seamless config roles [--json]
seamless config diff <file>
seamless config apply <file> [--dry-run]

set parses the value as JSON, falling back to a string (for example seamless config set login_methods '["email_otp","passkey"]'). apply writes a local JSON config file after a confirmation prompt.

`users`

Admin user management. Requires an admin role.

seamless users list [--limit <n>] [--offset <n>] [--json]
seamless users delete <id>
seamless users credentials <id> [--json]
seamless users prepare-device-replacement <id> [--keep-sessions] [--keep-passkeys] [--keep-totp]

prepare-device-replacement is admin-assisted account recovery and needs an elevated (stepped-up) session.

`org`

Admin organization and membership management. Requires an admin role.

seamless org list [--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>

Removed Or Not Currently Shipped

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

seamless deploy
seamless destroy
seamless contribute

Help And Version

If no command is provided, the CLI prints help.

seamless --help
seamless --version

Part of the Fells Code family

Seamless Auth Seamless Secrets Review Board Seamless CLI Seamless Glance