CLI Reference
Quick-reference table and flag reference for the lumio CLI.
Installation
npm install -g @zaflun/lumio-cli
# or
pnpm add -g @zaflun/lumio-cli
Commands
| Command | Description |
|---|---|
lumio login | Authenticate to your developer account |
lumio logout | Remove stored credentials |
lumio init | Scaffold a new extension |
lumio dev | Start local development server |
lumio build | Build for production |
lumio deploy | Deploy a new version |
lumio status | Show extension status |
lumio logs | Stream server function logs |
lumio secrets set <KEY> <VALUE> | Store a secret |
lumio secrets delete <KEY> | Delete a secret |
lumio secrets list | List secret key names |
lumio login
lumio login [--token <api_key>]
Without --token, opens a browser-based OAuth flow. With --token, uses the provided API key directly (useful in CI).
| Flag | Description |
|---|---|
--token <key> | Authenticate with an API key instead of browser flow |
lumio init
lumio init [name] [--template <template>]
| Flag | Description |
|---|---|
--template <name> | Scaffold from a template: blank, alert, scoreboard, poll, chat |
--dir <path> | Directory to create the project in (default: ./<name>) |
lumio dev
lumio dev [--port <port>] [--no-open]
Starts a local development server with hot module replacement. Opens the preview URL in the browser automatically.
| Flag | Description |
|---|---|
--port <n> | HTTP port for the dev server (default: 3010) |
--no-open | Do not open the browser automatically |
--mock <file> | Load a mock events file for simulating stream events |
The dev server injects a mock Lumio runtime so useLumioEvent, useLumioConfig, and useLumioAction all work without a real connected overlay.
lumio build
lumio build [--outdir <path>]
Compiles and bundles all surfaces for production. Output goes to dist/ by default.
| Flag | Description |
|---|---|
--outdir <path> | Output directory (default: dist) |
--analyze | Print bundle size breakdown after build |
Build fails if:
- A surface bundle exceeds 5 MB (gzipped)
- TypeScript type errors are present
lumio.config.jsonfails schema validation
lumio deploy
lumio deploy [--version <semver>] [--changelog <text>] [--dry-run]
Builds the extension and submits it as a new version for review. Equivalent to lumio build followed by POST /extensions/:id/versions.
| Flag | Description |
|---|---|
--version <semver> | Override version from lumio.config.json |
--changelog <text> | Short changelog for this version |
--dry-run | Build and validate but do not upload |
--no-build | Skip the build step (use existing dist/) |
After deploying, the version enters pending status and awaits review.
lumio status
lumio status [extension-id]
Prints the current extension status, latest version, install count, and pending review details.
| Flag | Description |
|---|---|
--json | Output as JSON |
lumio logs
lumio logs [--tail] [--since <duration>] [--level <level>]
Streams server function logs to stdout. Requires the extension to have server functions enabled.
| Flag | Description |
|---|---|
--tail | Follow new logs in real time (default: true) |
--no-tail | Print recent logs and exit |
--since <duration> | Show logs from the past duration, e.g. 1h, 30m, 7d |
--level <level> | Filter by log level: debug, info, warn, error |
--json | Raw JSON log output |
lumio secrets
lumio secrets set <KEY> <VALUE>
lumio secrets delete <KEY>
lumio secrets list
Manages secrets stored in Lumio Vault for your extension. Secrets are available in server functions via ctx.secrets.get().
| Subcommand | Description |
|---|---|
set <KEY> <VALUE> | Create or update a secret |
delete <KEY> | Delete a secret |
list | List key names (values are never shown) |
Secret keys must match [A-Z][A-Z0-9_]* (uppercase, starting with a letter).
Environment variables
| Variable | Description |
|---|---|
LUMIO_API_KEY | API key — overrides stored credentials |
LUMIO_EXTENSION_ID | Extension ID — overrides lumio.config.json |
LUMIO_API_URL | Override the API base URL (for self-hosted / staging) |
NO_COLOR | Disable colored output |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | General error (see stderr) |
2 | Authentication error |
3 | Validation error (config or bundle) |
4 | Network error / API unreachable |
5 | Rate limit exceeded |