LumoAuth CLI
The lumo CLI is the fastest way to drive LumoAuth from the terminal: sign in with your browser, spawn ephemeral sandbox organizations, forward webhooks to localhost, scaffold starter projects, and query audit logs. It also exposes the full administration surface for users, roles, OAuth clients, agents, webhooks, MFA policy and audit logs.
brew install lumoauth/tap/lumo # macOS / Linux; other channels below
lumo login --org acme-corp
That's the canonical first 30 seconds. Everything below is a deeper dive.
Why a CLI
Three audiences benefit:
- Developers building local-first apps —
lumo initscaffolds a working Next.js / Express / FastAPI / Go project;lumo tunnelforwards live webhook events to localhost;lumo dev startgives you a throwaway organization for branch previews. - Org admins — full create, read, update and delete over users, roles, groups, OAuth clients, agents, webhooks, audit logs, settings, MFA policy, sessions, and social providers without leaving the terminal.
- AI coding agents — auto-JSON output, structured errors, typed exit codes, no interactivity, and a
lumo apiraw passthrough for endpoints not covered by named commands.
Install
brew install lumoauth/tap/lumo # macOS / Linux
scoop install lumo # Windows (after: scoop bucket add lumoauth https://github.com/lumoauth/scoop-bucket)
winget install --id LumoAuth.lumo # Windows
curl -fsSL https://raw.githubusercontent.com/LumoAuth/cli/main/install.sh | sh # anywhere else; no sudo, installs to ~/.local/bin
Release archives and go install are also available, and lumo upgrade keeps any install current.
Authenticate
Two paths — pick whichever fits the context.
| Path | When | How |
|---|---|---|
| Device-flow login (sign in on another device: approve in a browser) | Humans on a workstation | lumo login --org <slug> |
| API key | CI, scripted use, AI agents | export LUMO_API_KEY=lmk_... && export LUMO_ORG=<slug> |
Stored credentials live at ~/.lumoauth/credentials.yaml (mode 0600). API keys live wherever you store secrets.
Command reference
| Section | Command(s) |
|---|---|
| Sign-in | login [--scope …] [--profile …] [--no-browser], logout, whoami |
| Diagnose | doctor — credentials, scopes, connectivity |
| Profiles | profile list/use/create/delete/show — named credential sets for several organizations or deployments |
| Configuration | config init/show/set <key> <value> — keys org_id, api_key, base_url, format, insecure in ~/.lumoauth/config.yaml |
| Maintenance | version, upgrade [--check] [--exec], completion <bash|zsh|fish|powershell> |
| Sandboxes | dev start, dev list, dev stop <slug> |
| Webhook tunnel | tunnel --to <url> [--filter <event>] |
| Project scaffolding | init --framework next|express|fastapi|go |
| Import from Auth0 | migrate auth0 --file <export.json> |
| Users | users list/get/create/update/delete/block/unblock/set-password, users roles get/set, users groups get/set |
| User MFA | users authenticators list/remove, users tap (temporary access code), users mfa-reset (deprecated; fails without calling the server) |
| Federated identities | users identities list/link/unlink, identities legacy-saml [--relink] |
| Roles & permissions | roles list/get/create/update/delete, permissions list/get/create/update/delete |
| Groups | groups list/get/create/update/delete, groups members list/add/remove |
| OAuth clients | apps list/get/create/update/delete/rotate-secret |
| Agents | agents list/get/create/update/delete/enable/disable/rotate-credentials/token |
| MCP servers | mcp servers, mcp discovery <server-id>, mcp test <server-id> <agent-id> |
| Webhooks | webhooks list/get/create/update/delete, webhooks deliveries list/get/replay |
| Audit logs | logs list/get/stats/export |
| Organization | org get, org update --name … --set key=value |
| Settings | settings get/update <area> (general, authentication, security, email, branding, scim, organization; settings get all) |
| MFA policy | mfa policy get, mfa policy set, mfa coverage |
| Sessions & tokens | sessions list/revoke/revoke-all, tokens list/revoke |
| Social providers | social list/get/create/delete |
| Raw API | api <METHOD> <path> — paths relative to the Admin API; absolute /orgs/… and /api/… paths work too; --raw for anything else |
Run lumo --help or lumo <command> --help for the in-binary reference at any time.
Every command takes the global --org <slug> flag (or LUMO_ORG); without
it the CLI uses the organization stored by lumo login in the active profile.
--org-id and LUMO_ORG_ID still work for existing scripts.
Global flags
--api-key string Organization API key lmk_… (overrides LUMO_API_KEY)
--org string Organization slug (overrides LUMO_ORG and the active profile)
--base-url string Base URL (overrides LUMO_BASE_URL)
--profile string Named credentials profile (overrides LUMO_PROFILE and current_profile)
-o, --output string Output format: table, json, yaml (default: table; json when piped)
--insecure Skip TLS certificate verification (local dev only)
-q, --quiet Suppress non-essential output
-v, --verbose Enable verbose output
Configuration precedence
Settings (organization, base URL, output format) resolve flags > environment > config file > active profile:
| Priority | Method | Example |
|---|---|---|
| 1 (highest) | CLI flags | --org acme-corp --base-url https://eu.app.lumoauth.dev |
| 2 | Environment variables | LUMO_ORG, LUMO_BASE_URL, LUMO_API_KEY, LUMO_OUTPUT_FORMAT, LUMO_INSECURE, LUMO_PROFILE, LUMO_CONFIG_DIR |
| 3 | Config file | ~/.lumoauth/config.yaml (org_id, api_key, base_url, format, insecure) |
| 4 (fallback) | Active profile | ~/.lumoauth/credentials.yaml (written by lumo login) |
The profile itself is chosen as --profile flag > LUMO_PROFILE > current_profile in the credentials file. Which credential is sent is decided separately; see Authentication.
A typical session
# Day 1 — install + sign in
brew install lumoauth/tap/lumo
lumo login --org acme-corp
# Spin up a throwaway sandbox for a feature branch
SLUG=$(lumo dev start --name pr-1234 -o json | jq -r '.data.slug')
# → sandbox-pr-1234-7a3b21
# Scaffold a working Next.js app pre-wired to the sandbox
lumo init --framework next --dir ./web --org "$SLUG"
cd web && npm install && npm run dev &
# In another terminal: forward webhook events to the dev server
lumo tunnel --to http://localhost:3000/api/webhooks --org "$SLUG"
# When the PR ships, tear down the sandbox
lumo dev stop "$SLUG"
Output formats and AI-agent friendliness
Every command supports -o json and -o yaml. The CLI auto-detects non-TTY environments and switches to JSON automatically — no flag needed when piping to jq, into a script, or into an AI agent's tool call.
lumo users list -o json | jq '.data[].email'
Exit codes: 0 success · 1 general error · 2 authentication or authorization · 3 not found · 4 invalid input (HTTP 400, 409, 422) · 5 rate limited. In JSON mode an error is {"error": true, "message", "hint", "status", "code", "details"}; hint says how to fix it (for example the exact lumo login --scope …).