Command Line Tools

Command Line Tools

The web UI (docker compose up, see Getting Started) is the primary way to use xLightsAI. Underneath it, everything is also available as a CLI — xlight-analyze — useful for scripting, batch processing, or working without the browser dashboard.

Run any command inside the dev container:

docker compose exec xonset xlight-analyze --help

(Or, in a local checkout with dependencies installed directly: python -m src.cli isn't runnable as a module — use the installed xlight-analyze console script, or python -c "from src.cli import cli; cli()".)

Command groups

xlight-analyze --help lists every command. The most commonly used ones:

Command	What it does
analyze	Run hierarchical analysis on an MP3 file or directory
full	Full analysis: all algorithms + stems + phonemes
summary	Print the scored summary table from an existing analysis
review	Launch the track review UI in the default browser
story	Build a song story interpretation from an existing analysis
story-review	Open the song story review UI in the browser
group-layout	Generate xLights Power Groups from a layout file
grouper-edit	Open the interactive layout group editor in a browser
generate	Generate an xLights .xsq sequence from an MP3 and layout
generate-wizard	Interactive wizard for sequence generation
wizard	Interactive wizard for configuring and launching the full pipeline
pipeline	Run the full xLights export pipeline end-to-end
library	Manage the user's analyzed song library
variant	Manage the effect variant library
scoring	Manage scoring configurations and profiles
export / export-xlights	Filter/export timing tracks and feature curves

There are also lower-level tools for tuning individual detectors: params, sweep / sweep-init / sweep-matrix / sweep-results / sweep-save / sweep-suggest, tune / tune-apply / tune-status, chord-stats, stem-inspect / stem-review, rotation-report, and story-diff / story-history.

Every command supports --help for its own options, e.g.:

docker compose exec xonset xlight-analyze generate --help

Typical CLI flow

Roughly mirrors the web UI's tab order:

# 1. Analyze a song (writes song_hierarchy.json next to the MP3)
xlight-analyze analyze song.mp3

# 2. Inspect the result
xlight-analyze summary song_hierarchy.json

# 3. (optional) review interactively
xlight-analyze review song_hierarchy.json

# 4. Build the song story (section roles, energy arc)
xlight-analyze story song.mp3

# 5. Generate Power Groups from your layout (once, per layout)
xlight-analyze group-layout layout/xlights_rgbeffects.xml

# 6. Generate the sequence
xlight-analyze generate song.mp3 layout/xlights_rgbeffects.xml

For an end-to-end run without stepping through each stage manually, use xlight-analyze pipeline or the interactive xlight-analyze wizard.

Developer commands

For contributors, there's also xlight-evaluate (acceptance gate, microscope visual-quality tooling) — see CLAUDE.md in the repository root ("Pre-merge acceptance gate" and "Visual-quality microscope" sections) for details:

xlight-evaluate gate            # full acceptance gate (~3-5 min)
xlight-evaluate gate --quick    # quick mode
xlight-evaluate microscope --help