# Budget (/advanced/budget) A budget is the work one render is allowed to do. Lumis bounds two dimensions of it, and says so in the output when either one runs out. ## Why a render needs a bound Highlighting cost is not a function of input size. A parse can retry, a query pattern can stay open across a large subtree, and a malformed document can drive either far past what its byte count suggests. A 40 KB file that is mostly one unterminated construct can cost more than a 4 MB file that parses cleanly, so "reject anything over N bytes" does not bound anything. Time does. ## The two dimensions | Dimension | Option | Default | Bounds | | --- | --- | --- | --- | | Query matches | `budget.match_limit` | 8192 | in-progress query matches tree-sitter keeps, for the highlight and bracket queries alike | | Wall clock | `budget.time_limit` | 5000 ms | the whole render — parse and query walk together | Both dimensions bound the same render, so they are one `budget` option rather than two loose ones; set only the one you care about and the other keeps its default. `time_limit` is **milliseconds in every runtime**, including Rust. It does not count language loading. Not the root language, which is ready before the clock starts, and not the languages an injection names — those load in the middle of the walk, and the time they take is given back. A parser download and compile costs hundreds of milliseconds against a render measured in single digits, so charging it would mean the first document to use a language came back plain and the next one did not, with nothing about either document to explain the difference. [Load languages ahead of time](/languages) if a first request should not pay the latency either. ## Exhaustion is never an error Parser failures are separate from budget exhaustion. If a parser returns no tree without an interrupt, Lumis reports a parse error. Increasing the time limit will not fix a crashing parser. Rust exposes `ParseFailed`, Elixir returns `%Lumis.RenderError{reason: :parse}`, and JavaScript and the CLI report which language failed to parse. Neither bound raises, returns an error tuple, or truncates. The document comes back whole, in the formatter you asked for. What changes is how much of it is highlighted, and the two bounds differ there: - **Time** returns **the whole document, unhighlighted**. A render stopped part way has no tree left to highlight from, so there are no scopes to emit. - **Matches** returns **the whole document, still highlighted**, with some scopes missing. Tree-sitter drops in-progress matches at the limit and keeps going, so the output is ordinary highlighted output that is less complete than it would otherwise be. A page that renders a code block slowly and correctly stays a page. One that raises turns a large paste into a 500. Partial highlighting is deliberately not offered for the time limit. Stopping a query walk halfway produces output that is coloured down to an arbitrary byte and bare after it, which reads as a rendering bug rather than as a limit. ## The marker Every HTML formatter marks the `
` when a budget was exhausted: ```html... ``` | Value | Meaning | | --- | --- | | `time` | the time limit was reached | | `matches` | tree-sitter dropped matches at the match limit | `matches` is the case that needs the attribute most: the output is ordinary highlighted output, and nothing else distinguishes it from a document that genuinely had few captures. Style it, log it, count it, or ignore it. Lumis attaches no behaviour to it. ```css pre.lumis[data-lumis-budget] { border-left: 2px solid var(--warn); } ``` The terminal and BBCode formatters have no attribute channel, so they report nothing. They still degrade the same way — plain text on the time limit, missing scopes on the match limit — the caller just has no way to tell. Event-stream APIs return events only, so they carry no marker either; the rendering entry points are where it appears. A [custom formatter](/formatters/custom) is told which limit applied and decides for itself what to do with it. ## Setting the limits ### JavaScript / TypeScript ```ts import { highlight, htmlInline } from "@lumis-sh/lumis"; const html = await highlight(source, htmlInline({language, theme}), { budget: { timeLimit: 2000, // milliseconds matchLimit: 16384, }, }); ``` `timeLimit: 0` removes the time limit. The budget applies to the native addon and to the portable `web-tree-sitter` runtime, including in browsers. ### Elixir ```elixir Lumis.highlight(source, budget: [ # milliseconds time_limit: 2_000, match_limit: 16_384 ] ) ``` `time_limit: 0` removes the time limit; omitting it uses the 5000 ms default. ### Rust ```rust use lumis::highlight::{Budget, HighlightOptions}; // milliseconds let options = HighlightOptions::new().budget(Budget::new().time_limit(Some(2_000)).match_limit(16_384)); // No time limit. let unbounded = HighlightOptions::new().budget(Budget::new().time_limit(None)); ``` The unit is milliseconds here too, rather than a `Duration`, so that one number means the same thing in every runtime. `Some(0)` also removes the time limit. ### CLI ```bash lumis highlight big.json --budget-time-limit 2000 --budget-match-limit 16384 ``` A CLI has no nesting, so the group becomes a flag prefix. `--budget-time-limit 0` removes the time limit. `lumis4j` does not expose these options; it is maintained in a separate repository. ## The limit is a bound, not a stopwatch The time limit is checked where tree-sitter offers to be interrupted, during the parse and during the query walk. Those points are frequent on ordinary content and the render stops within a few milliseconds of its limit. They are not uniform: on a document built to be pathological, a single step between two checks can run long, and the render overshoots. The portable `web-tree-sitter` runtime overshoots furthest, because its query walk offers fewer of them. So treat the limit as a ceiling on the order of magnitude, not a deadline you can schedule against. If a render must return within a hard wall-clock bound, enforce that where you can cancel the work — a worker with a timeout, a request deadline — and use the time limit to keep the common case cheap. ## Choosing a value The default is 5000 ms because it is far above what real content costs and far below what a browser or a proxy will wait. Across Lumis's own corpus the 99th percentile render is about 13 ms; content that legitimately takes seconds is megabytes long. Lumis deliberately publishes no bytes-per-second rule of thumb. Throughput varies by more than two orders of magnitude between languages and between well-formed and malformed documents of the same language, so any such number would be wrong in the cases that matter. Measure your own content, then leave headroom. Lower it when a render happens on a request path and a slow one is worse than a plain one. Raise it for a batch job rendering documents you know are large and valid. Remove it only where nothing is waiting on the result. ## Related - [Match limit](/usage/highlight#match-limit) — what the match bound does inside tree-sitter, and when scopes go missing - [Languages](/languages) — load languages ahead of the first render # Declaring parsers (/advanced/lock) A parser is a dependency. You add it, your package manager pins it, and it is there — or you did not add it, and it is not. Declaring parsers makes output reproducible. The set is in a file you already review, pinned by a lock you already have, so every machine renders the same document with the same parsers, and the lock records which parser produced it. For an Elixir application that downloaded parsers before 0.9, see [Upgrading to 0.9](/migrate/elixir#upgrading-to-09). ## One rule, one place to look Every runtime resolves parsers the same way: **only the ones the project installed**, with no fallback that fetches anything else. A parser is a dependency, declared where that runtime's dependencies already live. | Runtime | Declares its parsers in | Pinned by | | --- | --- | --- | | Rust | `Cargo.toml` features | `Cargo.lock` | | JavaScript / TypeScript | `package.json` dependencies | your package manager's lockfile | | JavaScript in a browser | the packages it imports | the lockfile behind your bundle | | Elixir | `mix.exs` dependencies | `mix.lock` | | CLI | nothing | — | Rust links parsers statically. JavaScript installs `@lumis-sh/wasm-*`, and a browser, which has no project to read, declares by what it imports. Elixir depends on `lumis_wasm_*`, whose `priv/parsers` holds the bytes — so they travel into a release like any other dependency's assets, with no data directory to prepare and nothing to copy. The CLI is the exception, deliberately. It has no project and downloads what it needs, because a viewer is not the application whose output a declaration governs, and a highlighter that behaved differently depending on the directory you ran it in would be worse than one that does not. ### Elixir Add the parsers you want to `mix.exs`. There are no Lumis-specific commands: `mix deps.get`, `mix deps.update` and `mix.lock` already are them. ```elixir title="mix.exs" defp deps do [ {:lumis, "~> 0.10"}, {:lumis_wasm_rust, "~> 0.26.0"}, {:lumis_wasm_bundle_web, "~> 0.1"} ] end ``` A bundle is a package whose dependencies are its members, so it widens when it gains a language and `mix deps.update` picks that up — a visible `mix.lock` diff, not a silent change. ```bash title="Move a pinned version" mix deps.update lumis_wasm_rust ``` ```bash title="Stop using it" # remove the line from mix.exs, then mix deps.unlock --unused ``` A project that vendors parsers rather than depending on them can point at the directories instead. Same layout; only how they got there differs. ```elixir title="config/config.exs" config :lumis, parser_dirs: ["priv/parsers"] ``` ### JavaScript / TypeScript Install the parsers you want. Your package manager's lockfile pins them, so there is no separate Lumis lock. ```bash npm install @lumis-sh/wasm-rust @lumis-sh/wasm-json ``` Rust and JSON now highlight. A Markdown file with a Haskell block renders that block as plain text — Lumis will not go and fetch `haskell`. Install nothing and nothing highlights. There is no fallback that fetches a language the project did not install, the same way Rust cannot use a language that was not compiled in. Install a bundle for a set of them, and prefer a focused one: [loading the full set can exhaust](/languages#bundle-full-is-not-the-safe-default) the 128 MB Wasm store every language shares. `bundle-full` also leaves out `systemverilog`; install `@lumis-sh/wasm-systemverilog` if you need it. A bundle installs a set in one package: ```bash npm install @lumis-sh/wasm-bundle-web ``` Parsers are read out of `node_modules` — the manifest through each package's `./lumis.json` export — so nothing is fetched at runtime. A browser has no `node_modules`, so there the packages you import are the declaration. `import rust from "@lumis-sh/wasm-rust"` works in both, and nothing is fetched in a browser either; see [Where parsers come from](/usage/javascript#where-parsers-come-from). Supplying your own resolver is a declaration too, and takes precedence: a caller that said where parsers come from has answered the question the dependency list otherwise answers. ### Rust Parsers are Cargo features, so `Cargo.lock` and the `lumis` version pin them. Nothing is fetched at runtime. ```toml title="Cargo.toml" lumis = { version = "0.16", default-features = false, features = ["lang-rust", "lang-elixir"] } ``` ## What a language you did not add does Naming a language explicitly is your decision, so one you never depended on is an error rather than a silent download: ```elixir Lumis.Languages.load("haskell") #=> {:error, :not_installed} ``` A language an *injection* names is content rather than a decision — a fenced block in a README, say — so that block renders plain and the document is fine. A missing parser costs one block, not the page. ## Releases Nothing to prepare. Parsers are dependencies, so `mix release` carries them the way it carries any dependency's `priv/`: ``` _build/prod/rel/my_app/lib/lumis_wasm_elixir-0.26.3/priv/parsers/ elixir.lumis.json tree-sitter-elixir-0.26.3-....wasm ``` The released node reads them from there. There is no data directory to stage, no copy step, and no network at boot or at render time. `config :lumis, :data_dir` still has a job, a smaller one: it holds the compiled WASM module cache, which is a speed-up rather than a source. Point it somewhere writable and persistent and a restart skips recompiling; lose it and the first render of each language is slower and nothing else changes. ## Verification npm and Hex check every package they fetch against its published checksum, which your lockfile records, so a parser that arrives through a package manager is already verified. Lumis loads it as installed, beside the `lumis.json` that describes it, and refuses a package outside the Tree-sitter series this Lumis speaks. It checks a parser against the SHA-256 in `lumis.json` only when it downloads the bytes itself, through a resolver or the CLI. # WASM security (/advanced/wasm-security) Every Lumis runtime except the Rust crate runs Tree-sitter parsers as WebAssembly. Two inputs matter: the source code you highlight, and the parser that reads it. Highlighting source code you didn't write is safe. A parser is a dependency: the sandbox limits what its code can do, and Lumis checks the bytes it downloads. ## Where parsers run | Runtime | Engine | A parser runs in | | --- | --- | --- | | Node with the native addon, Elixir, CLI | [Wasmtime](https://wasmtime.dev) 36, through Tree-sitter's Wasm store | a Wasmtime sandbox with a fixed import list | | Browsers, Bun, Deno, Node without the addon | `web-tree-sitter` 0.26 (Emscripten) | the JavaScript engine's WebAssembly sandbox | | Rust | none | your binary. Parsers are C compiled in, like any other C dependency | `lumis4j` lives in a separate repository and isn't covered here. ## The source you highlight Lumis assumes it's hostile. - A parser only decides which byte ranges get which name from Lumis's fixed [scope list](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-core/src/highlights.rs#L6). The formatter [escapes the text](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-core/src/formatter/html.rs#L525), so neither the document nor the parser can put markup into HTML output. - The [budget](/advanced/budget) caps each render with a time limit and a match limit. Running out returns the document plain or partly highlighted, never an error. - Elixir renders on [dirty CPU schedulers](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/packages/elixir/lumis/native/lumis_nif/src/lib.rs#L668), so a slow render doesn't block the BEAM's normal schedulers. ## What the Wasmtime sandbox enforces Tree-sitter links each parser into a Wasm store it owns, on an engine Lumis creates with Wasmtime's [default configuration](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-wasm-runtime/src/runtime.rs#L1064-L1074). - Imports are an allowlist. A parser can import [24 libc functions](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm/stdlib-symbols.txt) (`malloc`, `memcpy`, `strcmp`, `towlower` and similar), the lexer callbacks, and a few [abort and no-op stubs](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L587-L638). Any other import [fails the load](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1120-L1149). Nothing on that list touches files, sockets, clocks or processes. - Memory is capped. A store's linear memory stops at [128 MiB](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L180) and a scanner's heap at [4 MiB](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/crates/language/wasm/src/stdlib.c#L16). Wasmtime bounds-checks every memory access, keeps the call stack out of linear memory, and type-checks indirect calls ([Wasmtime security](https://docs.wasmtime.dev/security.html)). - The host checks what crosses the boundary. Since [tree-sitter#5569](https://github.com/tree-sitter/tree-sitter/pull/5569), every read of language data out of WASM memory is [bounds-checked](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L373-L407), and a scanner's serialized state [can't overrun](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1904-L1907) the host buffer. - A trap only fails the current render. Tree-sitter [flags the store](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1752-L1787) and [stops the parse](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/parser.c#L1603-L1604), and Lumis returns an error for that render. Wasmtime 36 is a long-term support release and gets security fixes for 24 months ([release policy](https://docs.wasmtime.dev/stability-release.html)). ## Where parser bytes come from npm and Hex verify an installed parser against your lockfile, so Lumis loads it as installed. When Lumis downloads parser bytes itself (the CLI, a resolver, a browser fetching a parser asset), it checks them against the SHA-256 in the parser's language package ([Rust](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-wasm-runtime/src/store.rs#L739-L747), [JavaScript](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/packages/javascript/lumis/src/core/languages.ts#L713-L720)) and checks its own cache again on every read. CI builds each parser once and publishes it to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements). ## The compiled-module cache Wasmtime compiles each parser to machine code and caches it under `compiled/` in the [data directory](/languages#point-every-process-at-one-directory). It loads those files back as code without checking that it wrote them (the same caveat as [`Module::deserialize`](https://docs.rs/wasmtime/36.0.15/wasmtime/struct.Module.html#method.deserialize)), so anyone who can write that directory can run code in your process. Give it the permissions you give your application's code. ## Content Security Policy Lumis works under a policy without `'unsafe-eval'`. It needs [`'wasm-unsafe-eval'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#wasm-unsafe-eval) to compile WebAssembly; without it, loading fails at `Parser.init`. ```text Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' ``` Bundlers warn about two direct `eval` calls in `web-tree-sitter`. Emscripten uses them only to load JavaScript embedded in a parser, and Tree-sitter parsers carry none, so the policy can leave `eval` off. # Architecture (/architecture) Lumis has three core components: languages, themes, and formatters. Source code flows through a pipeline that turns it into styled output. ## Pipeline ```text source code | v Tree-sitter parser (language grammar + highlight queries) | v highlighted tokens (text + scope + byte range) | v theme (scope -> color/style mapping) | v formatter (tokens + styles -> HTML / ANSI / BBCode Scoped / custom output) ``` 1. Tree-sitter parses the source into a concrete syntax tree 2. Highlight queries map tree nodes to scope names (`keyword`, `function`, `string`, etc.) 3. The theme maps scopes to colors and styles (foreground, background, bold, italic) 4. The formatter turns each token + style into the final output format ## Components ### Languages 110+ Tree-sitter grammars. Each language has: - a parser (compiled to native code for Rust, WASM for the JavaScript / TypeScript package, Elixir, and the CLI) - highlight queries (mostly from [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter)) - injections for nested languages (e.g., CSS and JavaScript inside HTML) Dynamic runtimes receive parser and queries together in a self-contained, independently versioned `@lumis-sh/wasm-*` package. A small stable catalog maps language IDs to package names, and one Tree-sitter-compatible npm range applies to the whole catalog. A project installs or imports the packages it uses, and the CLI asks a CDN to resolve that range; either way the package supplies current queries and the exact integrity-pinned parser. Updating one language within the supported series does not require a runtime package release. ### Themes 200+ themes extracted from Neovim colorschemes. Each theme is a JSON file mapping Tree-sitter scopes to styles. Themes have a `name` and `appearance` (light or dark). ### Formatters Convert highlighted tokens into output: | Formatter | Output | | --- | --- | | HTML Inline | `` | | HTML Linked | `` | | HTML Multi-Themes | `` | | Terminal | ANSI escape codes | | BBCode Scoped | `[keyword-function-rust]fn[/keyword-function-rust]` | ## Crate structure ```text lumis-core internal: language detection, theme/style logic, the formatters and their builders lumis public Rust API, Tree-sitter adapter, re-exports the formatters lumis-cli CLI binary lumis-build build-time code generation lumis-wasm-runtime shared Tree-sitter WASM engine, lazy registry, and bounded worker pool ``` ## Package layers - The Elixir package (`packages/elixir/lumis`) uses a small Rustler NIF with a shared Wasmtime engine and loads parser WASM per language. - The JavaScript / TypeScript package (`packages/javascript/lumis`) uses a native addon over that same Wasmtime runtime on Node, and `web-tree-sitter` in browsers, with the same per-language parser assets either way. - The integration packages (`packages/javascript/markdown-it-lumis` and `packages/javascript/rehype-lumis`) build on top of that package for Markdown and HAST pipelines, and `packages/javascript/vite` drives the HAST one from Vite's HTML entry-point hook. # CLI Behavior (/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` ```bash 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. ```bash lumis highlight main.txt --language rust ``` ## When to rely on auto-detection Omit `--language` when the path, shebang, or source content should drive detection. ```bash 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=` 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. ```bash 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](/cli/commands#lumis-dump-tree) 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 is `auto`. ```toml [highlight] theme = "auto" ``` For terminal output, `auto` asks for the background, foreground and ANSI accent colors in one exchange. It chooses a light or dark theme from the foreground against the background, or from background lightness if only the background is available. Monochrome themes and themes with poor default text contrast are excluded. The closest backgrounds are considered first. Within a small background tolerance, the foreground and then the ANSI accents distinguish similar themes. This can recognize a theme whose background has been changed slightly, but cannot identify every terminal theme. Use an explicit `--theme` when you want a particular one, including a monochrome theme. If the terminal reports no background, does not answer within one second, or has no close match, Lumis renders without a theme and explains why on stderr. Partial replies still work: foreground and ANSI colors are optional. A terminal reply that arrives after Lumis exits can appear as text at the shell prompt. Set a theme explicitly if this happens; an explicit theme skips the terminal query. Automatic selection only queries when stdout is a terminal and the formatter is `terminal`. Pipes, redirected output and HTML output render without a theme and print the reason on stderr. For colored output through a pager or styled HTML, select a theme explicitly: ```sh lumis highlight main.rs --theme dracula | less -R lumis highlight main.rs --formatter html-inline --theme github_light > main.html ``` An explicit `--theme` takes precedence over the config file. Set `XDG_CONFIG_HOME`, `LUMIS_CONFIG`, or `--config` to use a different config location. ## Parser cache lifecycle Highlighting downloads, verifies and loads whatever a file turns out to need, including languages injected inside it, and caches them for every later run. A Markdown file with a fenced Rust block highlights that block; a language that cannot be fetched leaves its own block plain rather than failing the file. The CLI stores language-package metadata and integrity-verified parser WASM files under the data directory. A cold cache resolves the runtime's compatible package range, then loads the exact parser version and matching queries named there. Parser filenames contain the package version and SHA-256 digest. A compatible manifest already in the store is used as is and never checked against the registry again. So a store staged during a build gives every run the same parser and query bytes, with no network at run time, and two stores filled on different days can hold different patch releases. Bytes that fail their digest check are discarded and fetched again, so a damaged store repairs itself. - first use of a language downloads its parser - `lumis languages download ...` persists selected parsers ahead of time, so no run pays for a download and the Wasmtime compile that follows it - `lumis languages download ... --force` resolves the package range again and replaces valid cached parsers ```bash lumis languages download rust javascript elixir lumis languages download rust --force ``` Parsers you build or vendor yourself go in the same `parsers/` directory as downloaded ones; `lumis --data-dir languages download ...` writes that layout. ## Data directory Default location depends on the OS. Override it with: - `--data-dir` - `LUMIS_DATA_DIR` The data dir stores: - language-package metadata, as `parsers/ .lumis.json` - parser WASM files, in the same `parsers/` directory - custom theme JSON files The metadata names the exact parser version, queries, and integrity digest, so a directory holding both is self-sufficient offline. ## Local custom themes Pass a JSON path directly to use a theme without installing it: ```sh lumis highlight main.rs --theme ./my-theme.json lumis themes show ./my-theme.json lumis themes build-css ./my-theme.json > my-theme.css ``` Paths are relative to the current working directory unless absolute. A missing or malformed explicit file produces an error rather than silently rendering without a theme. For short-name lookup, Lumis checks built-in names and then ` /themes/ .json`. `lumis themes list` discovers JSON files in that folder and marks them `(file)`. The name is the filename stem: `my-theme.json` is selected with `--theme my-theme`, regardless of the JSON's `name` field. Use an explicit path to select a file whose stem matches a built-in theme. The same lookup applies to `themes show`, `themes build-css`, and every `--themes key:theme` pair in multi-theme HTML, so `--themes dark:./my-theme.json` selects the same file as `--theme ./my-theme.json`. See [Generate a theme from a Neovim colorscheme](/recipes/generate-theme-from-neovim-colorscheme) for generation, loading examples, and license considerations, or [CLI](/usage/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, cache all relevant parsers. ## Verbose mode Use `--verbose` to inspect cache hits, parser paths, and downloads. # CLI Commands (/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 ` | `-d` | Override the data directory (also `LUMIS_DATA_DIR` env var) | | `--config ` | | 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 download` | 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 build-css` | Generate a theme stylesheet | | `lumis themes generate` | Generate a theme from a Neovim colorscheme repo | ## `lumis highlight` ```bash title="Terminal output (default formatter)" lumis highlight main.rs --theme catppuccin_frappe ``` ```bash title="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: ```bash 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 ` answers it for one formatter. Accepted by every formatter: | Flag | Short | Description | | --- | --- | --- | | `--language ` | `-l` | Language id (e.g., `rust`, `javascript`). Auto-detects from file if omitted. | | `--formatter ` | `-f` | Output format: `terminal` (default), `html-inline`, `html-linked`, `html-multi-themes`, `bbcode-scoped` | | `--rainbow-brackets` | | Render matched brackets by nesting depth | | `--word-diff` | | Mark the words that changed between removed and added lines. Only applies with `-l diff` | | `--highlight-lines ` | `-H` | Lines to highlight (e.g., `1,3-5,10`) | Accepted by `html-inline` and `terminal`: | Flag | Short | Description | | --- | --- | --- | | `--theme ` | `-t` | Built-in name, data-directory filename stem, JSON file path (e.g., `./my-theme.json`), or `auto` | Accepted by every formatter except `bbcode-scoped`, which has nothing to render a number into: | Flag | Short | Description | | --- | --- | --- | | `--line-numbers` | `-n` | Render a line number gutter | Accepted by `terminal`: | Flag | Short | Description | | --- | --- | --- | | `--background ` | `-b` | Fallback background: `theme`, a hex color, or omit to inherit | | `--width ` | `-w` | Render width for background padding, or `auto` | | `--highlight-lines-background ` | | Background for highlighted lines (defaults to the theme's `highlighted` background) | Accepted by `html-inline`, `html-linked` and `html-multi-themes`: | Flag | Short | Description | | --- | --- | --- | | `--structure ` | | `block` (default) writes a ` ` block; `inline` writes only the token spans, and the flags that configure the ``, ``, lines and header have no effect. See [Inline code](/formatters#inline-code) | | `--pre-class` | | CSS class appended to the wrapping ` ` tag | | `--pre-attr` | | Attribute for the wrapping ` ` tag; a bare name writes the boolean form. Repeat for more than one | | `--no-pre-attr` | | Attribute to leave off the wrapping ` ` tag | | `--code-attr` | | Attribute for the nested ` ` tag; a bare name writes the boolean form. Repeat for more than one | | `--no-code-attr` | | Attribute to leave off the nested ` ` tag, such as `tabindex` | | `--header-open` | | Opening tag wrapped around the output (requires `--header-close`) | | `--header-close ` | | Closing tag wrapped around the output (requires `--header-open`) | | `--highlight-lines-class ` | | CSS class added to highlighted lines | For an HTML background override, use `--pre-attr 'style=background-color: #181818;'`. Use `transparent` in place of the color to let an enclosing card show through. See [Override the block background](/formatters#override-the-block-background). Accepted by `html-inline` and `html-multi-themes`: | Flag | Short | Description | | --- | --- | --- | | `--include-highlights` | | Add `data-highlight` attributes naming each scope | | `--highlight-lines-style