SPAPS CLI Quickstart

Use this page when you are operating spaps from npm (npx spaps, npm install -g spaps, or project-local install).

Verified source: spaps 0.10.1 at Sweet Potato 5b09d3df1194577c5313c865fef1db98f694cdea. Prerequisites: Node.js 22+, Docker with Compose for local, and host port 3301 available unless SPAPS_LOCAL_PORT overrides it.

Read-only First Proof

If a runtime may already exist, inspect before starting or writing anything:


npx spaps --version
npx spaps status --json
npx spaps quickstart --json
npx spaps verify --json

A healthy local-mode verification has this shape (values vary):


{
  "success": true,
  "summary": "2/2 tests passed",
  "results": [
    { "test": "server_status", "success": true },
    { "test": "local_mode_contract", "success": true }
  ]
}

status, quickstart, verify, and tools inspect the selected runtime. local, init, create, fixtures, authentication commands, and domain control-plane commands can start services, create files, store credentials, or mutate server state. Run those only after checking the target mode and directory.

Standard Operator Flow

Inspect current state


npx spaps

Start local runtime


npx spaps local

Check auth mode hints


npx spaps quickstart --json

Authenticate CLI


npx spaps connect

Verify runtime + auth end to end


npx spaps verify --json

Create And Provisioning

Create a starter wired for SPAPS:


npx spaps create demo-app --template react

Provisioning outcomes:

Status	Meaning	Typical next step
`provisioned`	Local app and keys were created through self-service	Continue with generated `.env.local`
`local_mode`	Server local mode is active, so key provisioning is skipped	Keep working in local mode or provision later
`scaffold_only`	Starter files were generated, but no app provisioning happened	Re-run with `SELF_SERVICE_PASSWORD=...` when server is reachable

Supported templates are nextjs, react, node, and vanilla.

Fixtures Kernel

spaps fixtures manages repo-local auth fixtures under .spaps/:

.spaps/app.json
.spaps/users.json
.spaps/roles.json
.spaps/entitlements.json
.spaps/browser/ artifacts for Playwright and header/context replay

Common flows:


npx spaps fixtures init --base-url http://localhost:5173
npx spaps fixtures apply --base-url http://localhost:5173
npx spaps fixtures apply --seed --persona dayrate-entitled --base-url http://localhost:5173
npx spaps fixtures storage-state --persona admin

--seed is intended for local mode workflows and applies persona-declared seed requests before artifacts are emitted.

Auth Commands

Command	Purpose
`spaps login` / `spaps connect`	Device-flow login (RFC 8628)
`spaps whoami`	Read authenticated user identity
`spaps token`	Print current access token for piping to tools
`spaps logout`	Revoke and clear local credentials

Client-id resolution order for login/connect:

--client-id
SPAPS_CLI_CLIENT_ID
spaps.app.json
.spaps/app.json
/health/local-mode test application metadata

When local mode is not active, API key resolution for authenticated follow-up commands checks:

SPAPS_API_KEY
NEXT_PUBLIC_SPAPS_API_KEY
VITE_SPAPS_API_KEY
.env.local
.env

Credentials are stored at ~/.config/spaps/credentials.json (0600 permissions).

Runtime, Diagnostics, And Tooling Commands

Command	What it covers
`spaps local [stop]`	Start/stop local runtime
`spaps status`	Runtime availability check
`spaps quickstart`	Mode-aware startup guidance
`spaps verify`	Runtime/auth verification checks
`spaps init`	Writes starter `.env.local`
`spaps doctor`	Environment checks plus domain mount probes
`spaps docs`	Bundled docs browse/search
`spaps tools --json`	Emits AI tool contract from runtime + domain registry
`spaps help`	CLI quick help

spaps types is currently a reserved placeholder command and is not implemented yet.

Domain Control-Plane Commands

Command family	Purpose
`spaps dayrate config`	Fetch dayrate admin config
`spaps email <verb>`	Email send/template/preview/log/override workflows
`spaps policy list\|create\|delete`	Policy management
`spaps webhook list\|register`	Webhook registry management
`spaps issue-reports list-mine`	Caller issue-report listing

Example control-plane calls:


npx spaps dayrate config --json
npx spaps email send --template-key welcome --to user@example.com --context '{"user_name":"Jane"}' --json
npx spaps policy list --json
npx spaps webhook register --url https://example.com/hook --events user.created,user.deleted --json
npx spaps issue-reports list-mine --status open --json

/packages/local-runtime for runtime source and data source behavior.
/tutorials/local-development for Python/Make backend workflows.
/guides/auth-and-local-mode for local-mode and API-key behavior inside the backend.