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 trigger | Send events and other input to a running dev session |
lumio build | Build for production |
lumio deploy | Deploy a new version |
lumio status | Show extension status |
lumio logs | Stream server function logs |
lumio env set <KEY> [VALUE] | Store a secret |
lumio env delete <KEY> | Delete a secret |
lumio env 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>] [--open] [--bot-module] [--platform <platform>] [--role <role>] [--seed <n>] [--no-cooldown] [--view editor|layer]
Starts the esbuild watcher and local mock-host sandbox. Editor, layer, and bot-module handlers share one session. The sandbox URL is printed; --open launches it in a browser. See lumio dev.
| Flag | Description |
|---|---|
--port <n> | HTTP port for the dev server (default: 3100) |
--open | Open the browser automatically |
--bot-module | Open the chat panel first |
--platform <platform> | Default chat platform |
--role <role> | Default chat user role |
--seed <n> | Seed for generated event fields |
--no-cooldown | Disable local command cooldowns |
--view editor|layer | Surface to show first |
The dev server uses @zaflun/lumio-devkit so useLumioEvent, useLumioConfig, and useLumioAction work without a connected overlay.
lumio trigger
lumio trigger twitch:follower --count 50 --rate 5/s
Send a validated event, chat message, reward, music command, timer, or scenario to the running lumio dev session. See lumio trigger for field syntax and load options.
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 env
lumio env set <KEY> [VALUE]
lumio env delete <KEY>
lumio env list
Manages your extension's secrets (the extension in lumio.config.json). Bot-module handlers read them with ctx.secrets.get(); see Secrets.
| Subcommand | Description |
|---|---|
set <KEY> [VALUE] | Create or update a secret (PUT /v1/developer/extensions/{id}/secrets/{key}) |
delete <KEY> | Delete a secret |
list | List key names (values are never shown) |
Omit VALUE to keep the secret out of your shell history and the process list: the CLI then reads LUMIO_SECRET from the environment, or prompts with hidden input.
- Keys must match
^[A-Z0-9_]{1,64}$. - Values are 1 to 4096 bytes.
The CLI checks both rules before it calls the API. A developer API key (lm_dev_) may manage secrets, so lumio env set works in CI:
lumio login --token "$LUMIO_DEV_KEY"
LUMIO_SECRET="$WEATHER_API_KEY" lumio env set WEATHER_API_KEY
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) |
LUMIO_SECRET | Value for lumio env set when no VALUE argument is given |
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 |