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 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 --help`	Print usage
`seamless --version`	Print the installed CLI version

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 auth mode
optionally includes the admin dashboard
generates a working local stack
writes seamless.config.json
creates docker-compose.yml

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

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

Removed Or Not Currently Shipped

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

seamless deploy
seamless destroy
seamless contribute

Do not document those commands as shipped unless they reappear in source.

Help And Version

If no command is provided, the CLI prints help.

seamless --help
seamless --version