# Terminal Formatter (/formatters/terminal)

ANSI escape codes for shell output.

## Options

| Runtime | Options |
| --- | --- |
| Rust | `language`, `theme`, `background`, `width`, `highlight_lines`, `line_numbers` |
| Elixir | `language`, `theme`, `background`, `width`, `highlight_lines`, `line_numbers` |
| JavaScript / TypeScript | `language`, `theme`, `background`, `width`, `highlightLines`, `lineNumbers` |
| Java | `withLang()`, `withTheme()`, `withFormatter(Formatter.TERMINAL)` |
| CLI | default formatter, `--theme`, `--background`, `--width`, `--highlight-lines`, `--highlight-lines-background`, `--line-numbers` |

A highlighted line is painted with a background, from `highlight_lines`'
`background` or the theme's `highlighted` style. See
[Line Highlighting](/recipes/line-highlighting).

## Example

### JavaScript / TypeScript

```js
import {highlight} from '@lumis-sh/lumis'
import {terminal} from '@lumis-sh/lumis/formatters'
import javascript from '@lumis-sh/wasm-javascript'
import frappe from '@lumis-sh/themes/catppuccin_frappe'

const ansi = await highlight(
  'const x = 1',
  terminal({
    language: javascript,
    theme: frappe,
    background: 'theme',
    width: 120,
  }),
)
console.log(ansi)
```

### Rust

```rust
use lumis::{
    highlight, languages::Language, themes,
    TerminalBackground, TerminalBuilder,
};

let ansi = highlight(
    "fn main() {}",
    TerminalBuilder::new()
        .language(Language::Rust)
        .theme(Some(
            themes::get("catppuccin_frappe").unwrap(),
        ))
        .background(TerminalBackground::Theme)
        .width(Some(120))
        .build()
        .unwrap(),
);

println!("{}", ansi);
```

### Elixir

```elixir
Lumis.highlight!(
  "fn main() {}",
  formatter:
    {:terminal,
     language: "rust",
     theme: "catppuccin_frappe",
     background: :theme,
     width: 120}
)
```

### Java

```java
import io.roastedroot.lumis4j.core.Formatter;
import io.roastedroot.lumis4j.core.Lang;
import io.roastedroot.lumis4j.core.Lumis;
import io.roastedroot.lumis4j.core.Theme;

var lumis = Lumis.builder().build();

var highlighter = lumis.highlighter()
    .withLang(Lang.JAVASCRIPT)
    .withTheme(Theme.CATPPUCCIN_FRAPPE)
    .withFormatter(Formatter.TERMINAL)
    .build();

var ansi = highlighter.highlight("const x = 1").string();
System.out.println(ansi);

lumis.close();
```

### CLI

```bash
lumis highlight main.rs --theme catppuccin_frappe
# same as:
#   lumis highlight main.rs \
#     --formatter terminal \
#     --theme catppuccin_frappe
lumis highlight main.rs \
  --theme catppuccin_frappe \
  --background theme
lumis highlight main.rs -b '#303446' -w 120
```


## Output format

Terminal output is plain text wrapped in ANSI escape sequences:

```text
\x1b[38;2;202;158;230mfn\x1b[0m \x1b[38;2;140;170;238mmain\x1b[0m() {}
```

- the source stays as terminal text, not HTML
- ANSI escape sequences set foreground color and text styles
- `background` / `--background` controls the fallback background: omit it to inherit the output background, use `theme` to reuse the theme background, or pass a hex color
- `width` / `--width` pads each rendered line to the requested width, which is only visible alongside `background`; in the CLI, `auto` uses the current terminal width when available, and `-w` is the short form
- a tab counts as four columns when measuring a line for padding, in every runtime
- `\x1b[0m` resets formatting between styled segments

## When to use it

- CLI tools
- logs and local scripts
- previewing highlighted code in a terminal