Skip to content

Seamless Auth CLI

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

Current commands cover:

  • scaffold a Seamless Auth project from the starter template registry (React, Next.js, Express, Fastify, Expo)
  • add Seamless Auth to an existing project with seamless add
  • configure the auth server in Docker or local-source mode
  • optionally include the admin dashboard
  • validate generated config, Docker Compose, containers, and local health endpoints
  • make the owner email you give init the first admin
  • 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.


seamless-cli package
-> seamless binary
-> init local project
-> check local runtime
-> register as the owner, who becomes the first admin

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

Terminal window
npx seamless-cli --help

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

Terminal window
seamless --help

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


Terminal window
npx seamless-cli init my-app

Creates a new Seamless Auth project. The web, backend, and optional mobile starters are chosen from the seamless-templates registry, and the project also gets Docker Compose wiring, seamless.config.json, and either a Docker-based auth server or local auth server source depending on your prompt choices. It also asks for your email, which becomes the owner: registering with that address makes you the first admin.

Template flags such as --oauth (the OAuth example, which also prompts for Google, GitHub, Microsoft, and GitLab providers) skip a layer’s prompt. Run seamless templates list to see them, and see the CLI Init Flow for what each step does.


Terminal window
npx seamless-cli add --local --email=you@example.com
npx seamless-cli add --app <application-id>

Adds Seamless Auth to a project you already have. It finds an Express, Fastify, Go, Axum, FastAPI, or Django backend and a React, Angular, Vue, or SvelteKit web app, connects a local auth server (written to seamless/) or a managed application, writes the backend’s .env and the web app’s API URL, installs the packages, and prints the code to add. It never edits your source files. Next.js is not wired. See Add Seamless Auth To An Existing App.


Terminal window
npx seamless-cli check
npx seamless-cli check --strict

Validates the generated project shape and runtime:

  • seamless.config.json
  • configured web, API, and mobile paths
  • Docker availability, docker-compose.yml, and the expected running containers
  • health endpoints for the API, the auth server, and the admin console (wherever the project’s admin mode serves it)

Every check runs and reports. Without --strict the command exits 0 even when a check fails; with --strict it exits 1 on any failure, which suits CI. For a managed project the Docker checks are skipped and the managed instance’s health endpoint is probed instead. The CLI command reference lists every probe.

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


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


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.

Terminal window
seamless profile add work --instance-url <your-auth-server-url>
seamless profile list
seamless profile use work
seamless profile remove work

On the managed path, --instance-url is your application’s Auth Server URL, copied from Credentials → Auth API Configuration in the portal. Profiles are named pointers to Seamless Auth instances, stored in ~/.config/seamless/config.json (respects XDG_CONFIG_HOME). The config file holds only non-secret instance and identity metadata, not tokens. Set the active profile per command with --profile <name> or the SEAMLESS_PROFILE environment variable.

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

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

Lists and revokes sessions for the logged-in user.

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.


If no command is provided, the CLI prints help. Scaffolding always goes through init: a bare project name such as npx seamless-cli my-app is rejected as an unknown command.

The same behavior applies to the binary:

Terminal window
seamless my-app

The CLI will:

  1. Ask configuration questions, with framework options read from the template registry
  2. Copy the chosen web, API, and mobile templates into the project
  3. Configure the auth server in Docker or local-source mode
  4. Optionally include the admin console
  5. Generate Docker Compose, each starter’s .env, and seamless.config.json

See the CLI Init Flow for the details of each step.


web/
api/ # absent for a full-stack template
mobile/ # only when a mobile template is chosen
auth/ # only in local auth mode
admin/ # only in admin source mode
docker-compose.yml
seamless.config.json

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

seamless add wires an existing project’s environment and packages and prints the code, but does not edit source files, and does not support Next.js. See Add Seamless Auth To An Existing App.

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


Continue to CLI Init Deep Dive.