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`		Print help for any command

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 languages list`	List supported languages and file patterns
`lumis themes list`	List built-in and local themes
`lumis themes generate`	Generate a theme from a Neovim colorscheme repo
`lumis parsers fetch`	Pre-download parser WASM files
`lumis parsers update`	Refresh cached parser WASM files

`lumis highlight`

Terminal output (default formatter)

lumis highlight main.rs --theme dracula

Pipe from stdin

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

Options

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`
`--theme <name>`	`-t`	Theme name (e.g., `dracula`, `github_dark`) or `auto`
`--themes <key:theme>`		Theme pair for multi-themes (repeatable, e.g., `--themes light:github_light --themes dark:github_dark`)
`--default-theme <id>`		Which `--themes` entry gets inline styles
`--css-variable-prefix <prefix>`		Prefix for CSS custom properties (default: `--lumis`)
`--highlight-lines <lines>`	`-h`	Lines to highlight (e.g., `1,3-5,10`)

Examples

HTML inline

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

HTML linked

lumis highlight main.rs -f html-linked

HTML multi-themes

lumis highlight main.rs \
  -f html-multi-themes \
  --themes light:github_light \
  --themes dark:github_dark \
  --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 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. Parser WASMs are downloaded and cached on first use when needed.

`lumis languages list`

lumis languages list

Prints all supported languages with their file extensions and patterns.

`lumis themes list`

lumis themes list

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

`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

`lumis parsers fetch`

Pre-download parser WASM files so highlighting doesn't trigger downloads at runtime.

Selected parsers

lumis parsers fetch rust javascript elixir

All parsers

lumis parsers fetch --all

`lumis parsers update`

Re-download parsers to get the latest versions.

lumis parsers update rust javascript
lumis parsers update --all

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/ — cached Tree-sitter WASM files
themes/ — custom theme JSON files (visible in lumis themes list)

Global options​

Commands​

lumis highlight​

Options​

Examples​

lumis dump tree​

lumis dump events​

lumis languages list​

lumis themes list​

lumis themes generate​

lumis parsers fetch​

lumis parsers update​

Configuration​

Data directory​