CLI

Seamless Auth CLI

The Seamless Auth CLI is published as seamless-cli and exposes the seamless binary. It scaffolds a self-hosted local project, checks the generated stack, verifies auth conformance, and also acts as an authenticated client against a running Seamless Auth instance (log in, inspect sessions, and run admin operations).

Current commands cover:

• scaffold a React + Express Seamless Auth project
• configure the auth server in Docker or local-source mode
• optionally include the admin dashboard
• validate generated config, Docker Compose, containers, and local health endpoints
• bootstrap the first admin user
• verify the full auth surface with the seamless verify conformance harness
• log in to an instance and manage the active profile, session, and account
• run admin config, users, and org operations against an instance

The current ../seamless-cli source does not ship deploy, destroy, or contribute commands.

Note

The CLI does have a managed init flow. When a profile is logged in, init defaults to the managed path, When not logged in it will integrate the existing project. seamless init scaffolds a self-hosted local stack pointed at localhost; it does not read your logged-in profile or connect a scaffolded app to a hosted managed instance. For the managed path, follow the Managed Quickstart.

---

Mental Model

seamless-cli package
  -> seamless binary
  -> init local project
  -> check local runtime
  -> bootstrap first admin

---

Installation

No global install is required. Use the package through npx:

npx seamless-cli --help

If installed globally or linked locally, run the binary directly:

seamless --help

The package is named seamless-cli; the executable command is seamless.

---

Core Commands

init

npx seamless-cli init my-app

Or use the shortcut:

npx seamless-cli my-app

Creates a new Seamless Auth project. The generated project includes a React frontend, an Express API, Docker Compose wiring, seamless.config.json, and either a Docker-based auth server or local auth server source depending on your prompt choices.

---

check

npx seamless-cli check

Validates the generated project shape and local runtime:

• seamless.config.json
• configured web and API paths
• Docker availability
• docker-compose.yml
• expected running containers
• API, auth, and admin health endpoints on local ports

This command checks the local generated stack. It does not currently check Terraform, AWS CLI, or deployment state.

---

bootstrap-admin

npx seamless-cli bootstrap-admin admin@example.com

Creates a bootstrap admin invite for the first admin user.

The CLI resolves the bootstrap secret from local project files before prompting manually. It sends the request through the backend adapter at /auth/internal/bootstrap/admin-invite.

---

verify

seamless verify
seamless verify --local

Runs the cross-package auth conformance harness: it stands up the ecosystem with Docker Compose and runs a Playwright matrix across the api, adapter, and React (browser) layers, then prints a flow x layer pass/fail grid. Use --local to build the @seamless-auth/* packages from local source (pre-publish contract testing); the default tests the published packages. See the CLI command reference for all flags and environment overrides.

---

Account And Instance Commands

Beyond scaffolding, the CLI can authenticate against a running Seamless Auth instance and act as a client. It targets whichever instance is set in the active profile.

profile

seamless profile add work --instance-url https://<your-app-id>.seamlessauth.com
seamless profile list
seamless profile use work
seamless profile remove work

Profiles are named pointers to Seamless Auth instances, stored in ~/.config/seamless/config.json (respects XDG_CONFIG_HOME). The config file holds only non-secret instance and identity metadata, not tokens. Set the active profile per command with --profile <name> or the SEAMLESS_PROFILE environment variable.

login, whoami, logout

seamless login              # email OTP against the active profile's instance
seamless whoami             # show the current identity, profile, and instance URL
seamless logout             # end the session and clear local tokens
seamless logout --all       # revoke every session first, then clear local tokens

login authenticates with email OTP and stores the session in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service), not in a plaintext file.

sessions

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

Lists and revokes sessions for the logged-in user.

Admin commands

With an admin role on the target instance, the CLI can also run config, users, and org operations. See the CLI command reference for the full flag surface.

---

CLI Behavior

If no command is provided, the CLI prints help.

This is valid:

npx seamless-cli my-app

It is treated as:

npx seamless-cli init my-app

The same behavior applies to the binary:

seamless my-app

---

What Happens During init

The CLI will:

1. Ask configuration questions
2. Generate the React web starter
3. Generate the Express API starter
4. Configure the auth server in Docker or local-source mode
5. Optionally include the admin dashboard
6. Generate Docker Compose and local config

---

Generated Files

web/
api/
auth/                  # only in local auth mode
admin/                 # only in admin source mode
docker-compose.yml
seamless.config.json
README.md

---

Design Philosophy

The CLI is built to be:

• opinionated: secure defaults and a known project shape
• guided: interactive prompts for local stack generation
• explicit: generated config and service wiring are visible in the project
• local-first: the current source focuses on a repeatable development stack

---

Current Boundaries

The CLI still does not provide a polished “attach Seamless Auth to an existing application” flow.

Deployment automation is not part of the current seamless-cli command surface. Keep deployment docs status-based until deployment commands ship again in source.

---

Next Step

Continue to CLI Init Deep Dive.