CLI

Seamless Auth CLI

The Seamless Auth CLI is published as seamless-cli and exposes the seamless binary. It is the entry point for scaffolding a local Seamless Auth project, checking the generated stack, creating the first admin bootstrap invite, and verifying auth conformance across the ecosystem.

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

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

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.

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:

Ask configuration questions
Generate the React web starter
Generate the Express API starter
Configure the auth server in Docker or local-source mode
Optionally include the admin dashboard
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.