CLI Commands

Global options

These flags work with any subcommand:

Flag	Short	Description
`--verbose`	`-v`	Show extra output: downloads, cache hits, parser paths
`--data-dir <path>`	`-d`	Override the data directory (also `LUMIS_DATA_DIR` env var)
`--config <path>`		Override the config file (also `LUMIS_CONFIG` env var)
`--help`	`-h`	Print help for any command
`--version`	`-V`	Print the version

Commands

Command	What it does
`lumis highlight`	Highlight a file or stdin
`lumis dump tree`	Print configurable Tree-sitter syntax trees
`lumis dump events`	Print raw highlight events as JSON
`lumis formatters list`	List output formatters
`lumis formatters show`	List the options one formatter accepts
`lumis languages list`	List supported languages and file patterns
`lumis languages show`	Print what the catalog knows about one language
`lumis languages cache`	Download and compile parsers so later runs skip both
`lumis themes list`	List built-in and local themes
`lumis themes show`	Print one theme's appearance and colors
`lumis themes generate`	Generate a theme from a Neovim colorscheme repo

`lumis highlight`

Terminal output (default formatter)

lumis highlight main.rs --theme catppuccin_frappe

Pipe from stdin

cat main.rs | lumis highlight -l rust
echo 'const x = 1' | lumis highlight -l javascript --formatter html-inline --theme catppuccin_frappe

Options

Most options belong to a specific formatter. Passing one the selected formatter does not accept is an error naming both, rather than being silently ignored:

lumis highlight main.rs --pre-class code
# error: `--pre-class` is not accepted by the `terminal` formatter
#
#   HTML options apply to: html-inline, html-linked, html-multi-themes
#   run `lumis formatters show terminal` to see what it accepts

lumis highlight --help prints the same grouping, and lumis formatters show <name> answers it for one formatter.

Accepted by every formatter:

Flag	Short	Description
`--language <lang>`	`-l`	Language id (e.g., `rust`, `javascript`). Auto-detects from file if omitted.
`--formatter <fmt>`	`-f`	Output format: `terminal` (default), `html-inline`, `html-linked`, `html-multi-themes`, `bbcode-scoped`
`--rainbow-brackets`		Render nested brackets using rainbow bracket scopes

Accepted by html-inline and terminal:

Flag	Short	Description
`--theme <name>`	`-t`	Theme name (e.g., `catppuccin_latte`, `catppuccin_frappe`) or `auto`

Accepted by terminal:

Flag	Short	Description
`--background <bg>`	`-b`	Fallback background: `theme`, a hex color, or omit to inherit
`--width <n>`	`-w`	Render width for background padding, or `auto`

Accepted by html-inline, html-linked and html-multi-themes:

Flag	Short	Description
`--pre-class <class>`		CSS class appended to the wrapping `<pre>` tag
`--header-open <tag>`		Opening tag wrapped around the output (requires `--header-close`)
`--header-close <tag>`		Closing tag wrapped around the output (requires `--header-open`)
`--highlight-lines <lines>`	`-H`	Lines to highlight (e.g., `1,3-5,10`)
`--highlight-lines-class <class>`		CSS class added to highlighted lines

Accepted by html-inline and html-multi-themes:

Flag	Short	Description
`--italic`		Apply italic styles from the theme
`--include-highlights`		Add `data-highlight` attributes naming each scope
`--highlight-lines-style <style>`		`theme` (default), `none`, or raw CSS

Accepted by html-multi-themes:

Flag	Short	Description
`--themes <key:theme>`		Theme pair (repeatable, e.g., `--themes light:catppuccin_latte --themes dark:catppuccin_frappe`)
`--default-theme <id>`		Which `--themes` entry gets inline styles
`--css-variable-prefix <prefix>`		Prefix for CSS custom properties (default: `--lumis`). A value starting with `-` needs the `=` form: `--css-variable-prefix=--shiki`

Examples

HTML inline

lumis highlight main.rs -f html-inline -t catppuccin_frappe

HTML linked

lumis highlight main.rs -f html-linked

HTML multi-themes

lumis highlight main.rs \
  -f html-multi-themes \
  --themes light:catppuccin_latte \
  --themes dark:catppuccin_frappe \
  --default-theme light

BBCode Scoped

lumis highlight main.rs -f bbcode-scoped

Verbose mode — see cache hits and parser paths

lumis highlight main.rs -v

`lumis formatters`

List the formatters

lumis formatters list

html-inline        HTML with inline style attributes
html-linked        HTML with CSS class names (pair with a theme stylesheet)
html-multi-themes  HTML with CSS custom properties, one set per theme
terminal           ANSI escape codes (default)
bbcode-scoped      BBCode using highlight scope names as tags

See what one formatter accepts

lumis formatters show terminal

terminal: ANSI escape codes (default)

Accepted options:
  --language
  --formatter
  --rainbow-brackets
  --theme
  --background
  --width

Run `lumis highlight --help` for descriptions.

`lumis dump tree`

Print named syntax nodes as branch lines with language and zero-based range metadata. The host tree is shown by default. Options can add source text, resolved highlights, and query-driven injected language trees. Square brackets identify syntax nodes; @name lines identify resolved highlights.

Flag	Short	Description
`--language <lang>`	`-l`	Language id. Auto-detects from the path if omitted.
`--format <format>`		`lines` (default) or canonical `sexp` output
`--text[=<limit\|full>]`		Add JSON-escaped middle previews; defaults to 80 characters
`--highlights`		Add resolved highlight-query results in source order
`--injections`		Add injected language trees and their highlights

Parse a file with automatic language detection

lumis dump tree src/main.js

Add source text previews

lumis dump tree component.svelte --text
lumis dump tree component.svelte --text=120
lumis dump tree component.svelte --text=full

Limits from 1 to 3 show leading characters only. Larger truncated previews use ..., retaining both ends when space permits. Optional text values use = so --text component.svelte still treats the final argument as the input path.

Show a mixed-language annotated tree

lumis dump tree component.svelte --injections --text --highlights

Use the canonical parser representation

lumis dump tree src/main.js --format sexp

--format sexp cannot be combined with --text or --highlights. With --injections, each actual parser tree is printed as a separately labeled S-expression section.

Example mixed-language annotated tree
[document] language: svelte, range: 0:0-1:0, text: "function increment() { count++; }\n"
├── [text] language: svelte, range: 0:0-0:20, text: "function increment()"
└── [expression] language: svelte, range: 0:21-0:33, text: "{ count++; }"
    ├── @punctuation.bracket language: svelte, range: 0:21-0:22, text: "{"
    ├── [svelte_raw_text] language: svelte, range: 0:23-0:32, text: "count++; "
    │   └── [program] language: javascript, range: 0:23-0:32, text: "count++; "
    │       └── [expression_statement] language: javascript, range: 0:23-0:31, text: "count++;"
    │           ├── [update_expression] language: javascript, range: 0:23-0:30, text: "count++"
    │           │   ├── [identifier] field: argument, language: javascript, range: 0:23-0:28, text: "count"
    │           │   │   └── @variable language: javascript, range: 0:23-0:28, text: "count"
    │           │   └── @operator language: javascript, range: 0:28-0:30, text: "++"
    │           └── @punctuation.delimiter language: javascript, range: 0:30-0:31, text: ";"
    └── @punctuation.bracket language: svelte, range: 0:32-0:33, text: "}"

`lumis dump events`

Print the raw highlight event stream as JSON. Start events include the resolved highlight scope and language; source events use byte offsets into the original input.

Inspect highlight captures

lumis dump events src/main.js

Debug a partial mixed-language snippet

echo 'function increment() { count++; }' | lumis dump events -l svelte

All dump commands accept an optional path and --language / -l. They read stdin when the path is omitted, using the same language detection behavior as lumis highlight. Exact-version parser WASMs are verified and cached on first use when needed.

`lumis languages list`

lumis languages list

Prints all supported languages with their file extensions and patterns.

`lumis languages show`

lumis languages show elixir
lumis languages show js

Prints one language's id, name, aliases, extensions, globs, Emacs modes and shebangs. Aliases resolve the way highlighting resolves them, so js finds JavaScript. Exits non-zero on an unknown name.

`lumis languages cache`

Download exact, integrity-checked parser WASM files ahead of time, and compile them. Highlighting does both anyway; this moves them off the first run.

A cold parser costs a download and then a Wasmtime compile, and the compile is the larger half. See Filling the store at build time for how the CLI prepares the cache shared by every native runtime.

Selected parsers

lumis languages cache rust javascript elixir

A bundle

lumis languages cache bundle-web

The bundle-* names cover the same languages as the matching @lumis-sh/wasm-bundle-* package. Lumis.Languages.async_load/1, Lumis.Languages.cache/2 and JavaScript's cacheLanguages() accept the same names in application code.

All parsers

lumis languages cache --all

Replace valid cached parsers

lumis languages cache rust javascript --force

`lumis themes list`

lumis themes list

Lists built-in themes and any custom themes found in the data directory.

`lumis themes show`

lumis themes show catppuccin_frappe

Prints a theme's appearance, foreground, background and how many highlight scopes it defines. Finds themes in the data directory as well as built-in ones. Exits non-zero on an unknown name.

`lumis themes generate`

Extract a theme from a Neovim colorscheme Git repository.

Flag	Short	Description
`--url <url>`	`-u`	Git repository URL
`--colorscheme <name>`	`-c`	Colorscheme name to activate (e.g., `catppuccin-mocha`)
`--output <path>`	`-o`	Write JSON to this path (prints to stdout if omitted)
`--setup <lua>`	`-s`	Lua code to run before loading the colorscheme
`--appearance <mode>`	`-a`	`light` or `dark` (default: `dark`)

lumis themes generate \
  -u https://github.com/folke/tokyonight.nvim \
  -c tokyonight-night \
  -o tokyonight.json

Light theme

lumis themes generate \
  -u https://github.com/projekt0n/github-nvim-theme \
  -c github_light \
  -a light \
  -o github-light.json

Configuration

Lumis reads ~/.config/lumis/config.toml by default on macOS and Linux. Set XDG_CONFIG_HOME to change the base directory, or use --config / LUMIS_CONFIG to select another file.

[highlight]
theme = "auto" # or a theme name such as "tokyonight_moon"

auto queries the terminal background and selects the built-in theme with the closest background color. If the terminal cannot be queried, Lumis renders without a theme. An explicit --theme takes precedence over the config file.

Data directory

Lumis stores parser WASM files and custom theme JSON in a local data directory.

OS	Default path
macOS / Linux	`~/.local/share/lumis/`
Windows	`%APPDATA%/lumis/`

Override with --data-dir or LUMIS_DATA_DIR.

Contents:

parsers/ — verified Tree-sitter WASM files keyed by version and SHA-256
themes/ — custom theme JSON files (visible in lumis themes list)

Global options​

Commands​

lumis highlight​

Options​

Examples​

lumis formatters​

lumis dump tree​

lumis dump events​

lumis languages list​

lumis languages show​

lumis languages cache​

lumis themes list​

lumis themes show​

lumis themes generate​

Configuration​

Data directory​