lumio deploy

Upload a built extension bundle to Lumio as a new version. The version starts in draft status and must go through the submission wizard to enter the review process.

Usage

lumio deploy [-v <version>] [-d <description>] [--breaking] [--draft] [--token <token>]

Example

# Build first, then deploy
lumio build
lumio deploy -v 1.2.0 -d "Added live score updates from ESPN"

Or let it read the version from lumio.config.json automatically:

lumio deploy -d "Fixed score display alignment"

Options

Flag	Alias	Description
--version <semver>	-v	Version string (default: reads from lumio.config.json)
--description <text>	-d	Release notes / changelog for this version
--breaking	—	Flag this version as a breaking change (disables auto-update for existing installs)
--draft	—	Upload as draft without triggering the submission flow (default behavior — this flag is explicit)
--token <token>	—	API token for authentication (skips interactive login). Also reads from LUMIO_TOKEN env var
--outdir <path>	—	Location of the built bundle (default: dist)

Pre-flight checks

Before uploading, the CLI runs these validation checks:

1. Sound file format — each file in dist/sounds/ is validated against the supported audio formats (MP3, WAV, OGG, WebM, M4A, AAC, FLAC) and checked for existence
2. Sound count — the number of sound files is checked against the resolved max_sounds limit (fetched from the API via GET /v1/developer/extensions/{id}/limits)
3. Per-file size — each sound file is checked against the resolved max_sound_file_size limit
4. Total storage — the combined size of all sound files is checked against the resolved max_sound_storage_bytes limit
5. Manifest validation — lumio.config.json is validated against the extension schema

If any check fails, the deploy is blocked with a descriptive error message.

What happens on deploy

1. CLI reads lumio.config.json and validates the extension
2. All built files from dist/ are collected (JS, CSS, HTML, images, fonts, video, audio, JSON, Lottie, source maps)
3. Sound files placed in dist/sounds/ are registered as extension-bundled sounds — they appear in the account's sound library when the extension is installed
4. Each file is uploaded individually as a multipart files field alongside source.tar.gz, manifest, and release notes
5. A new ExtensionVersion record is created with status draft
6. Files are stored via lo-storage (S3/R2/local) at {extension_id}/versions/{version}/{file_path}
7. Each file gets a row in extension_version_files with content-type, size, and content hash

Supported file types

Category	Extensions
Code	.js, .css, .html, .map
Images	.png, .jpg, .jpeg, .gif, .svg, .webp, .avif, .ico
Video/Audio	.mp4, .webm, .ogg, .mp3, .wav
Fonts	.woff, .woff2, .ttf, .otf, .eot
Data	.json, .lottie

Size limits

Limit	Value
Per file	10 MB
Total upload	50 MB
Max files per version	200

Deploying Sports Scoreboard v1.2.0...

  Uploading 8 files (1.2 MB total)...
    layer.js         312 KB  application/javascript
    editor.js        525 KB  application/javascript
    styles.css        24 KB  text/css
    assets/logo.png   89 KB  image/png
    ...
  Upload successful. Status: draft
  Submit for review via the dashboard or `lumio status`.

Backward compatibility

Older CLI versions that send a single bundle field continue to work. The API treats the single bundle as bundle.js and processes it through the same pipeline.

CI/CD deployment

In CI environments, authenticate with either the LUMIO_TOKEN environment variable or the --token flag:

# Via environment variable
LUMIO_TOKEN=${{ secrets.LUMIO_TOKEN }} lumio deploy -v 1.2.0 -d "Automated release"

# Via --token flag
lumio deploy -v 1.2.0 -d "Automated release" --token ${{ secrets.LUMIO_TOKEN }}

The CLI detects CI=true and skips interactive prompts. When --token is provided, it takes precedence over the stored credential.

Breaking changes

Mark a version as breaking to prevent auto-updates for users who have not manually reviewed the breaking change notes:

lumio deploy -v 2.0.0 --breaking -d "Storage format changed — manual migration required"

Breaking versions show a notice in the extension store and require users to manually accept the update.

Exit codes

Exit code	Meaning
0	Deployment succeeded
1	Authentication error (run lumio login)
2	Validation error (missing build, invalid version, etc.)
3	Upload error (network failure, rate limit)
4	Extension not found (invalid Extension-ID)