Skip to main content

CLI Behavior

Input sources​

  • if a path is provided, Lumis reads that file
  • if no path is provided, Lumis reads from stdin
  • you can pipe content directly into lumis highlight or any lumis dump command
  • terminal output is the default highlight formatter unless you pass --formatter
cat main.rs | lumis highlight -l rust

echo 'fn main() {}' | lumis highlight -l rust

When to set --language​

Pass --language when you already know the correct parser and do not want detection to depend on the filename or input content.

lumis highlight main.txt --language rust

When to rely on auto-detection​

Omit --language when the path, shebang, or source content should drive detection.

lumis highlight main.rs

If no language can be inferred, plaintext is the safe fallback for highlighting. Dump commands instead ask you to pass --language, because they need a parser.

Parser and query debugging​

Use lumis dump tree to inspect named syntax nodes as branch lines with language and range metadata. --text, --highlights, and --injections add source text, resolved highlight-query results, and injected syntax trees. Text uses an 80-character middle preview by default; use --text=<limit> or --text=full to change it. Syntax nodes use [name]; resolved highlights use @name. Use lumis dump events when you need the raw highlight event stream.

lumis dump tree component.svelte

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

lumis dump tree component.svelte --format sexp

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

Both commands use the same path, stdin, language detection, parser download, and cache behavior as lumis highlight. See the CLI command reference for output details.

Theme selection​

When --theme is omitted, Lumis uses [highlight].theme from its config file. On macOS and Linux, the default path is ${XDG_CONFIG_HOME:-~/.config}/lumis/config.toml; on Windows it is %XDG_CONFIG_HOME%/lumis/config.toml, or %APPDATA%/lumis/config.toml when XDG is unset. The default value, auto, queries the terminal background and chooses the built-in theme with the closest background color.

[highlight]

theme = "auto"

If terminal color detection is unavailable, Lumis renders without a theme. An explicit --theme takes precedence. Set XDG_CONFIG_HOME, LUMIS_CONFIG, or --config to use a different config location.

Parser cache lifecycle​

The CLI stores parser WASM files under the data directory.

  • first use may trigger a parser download
  • lumis parsers fetch ... downloads ahead of time
  • lumis parsers update ... refreshes cached parsers
lumis parsers fetch rust javascript elixir

lumis parsers update rust

Data directory​

Default location depends on the OS. Override it with:

  • --data-dir
  • LUMIS_DATA_DIR

The data dir stores:

  • parser WASM files
  • custom theme JSON files

Local custom themes​

Themes placed in the data directory can be discovered by lumis themes list and used by name.

That is useful when you generate themes with lumis themes generate and want to keep using them locally.

See CLI Commands for theme generation flags and CLI for highlight workflow examples.

Nested languages and parser availability​

Some formats depend on nested parsers. If embedded languages are missing from the cache, those nested regions cannot be fully highlighted.

If you work with mixed-language content, prefetch all relevant parsers.

Verbose mode​

Use --verbose to inspect cache hits, parser paths, and downloads.