rs-rich-cli

The rs-rich-cli package is a Rust port of the rich-cli terminal toolbox — rich output for files, data and URLs, from the command line. Install it from crates.io with Cargo; the executable it installs is named rich:

cargo install rs-rich-cli
rich --help
rich --demo  # guided suite tour; Ctrl+C stops

rich README.md              # auto-detected and rendered as Markdown
rich data.csv               # rendered as a table
rich notebook.ipynb         # Jupyter notebook, cells and outputs
rich https://example.com    # fetched and syntax-highlighted
rich -p "[bold red]hi[/]"   # console markup
rich json data.json         # preferred subcommand form
rich jsonl events.ndjson    # streaming JSON Lines / NDJSON
rich log app.jsonl          # structured-log JSONL

Tools that upstream rich-cli does not have:

rich inspect deploy.yaml --select '$.servers[*].name'   # JSON/YAML/TOML/XML/INI/dotenv as a tree
rich mermaid flow.mmd                                   # a Mermaid flowchart, drawn as text
rich diff old.rs new.rs --side-by-side                  # text diff; `git diff | rich diff -` for patches
rich view src/main.rs --search todo                     # any file, rendered or highlighted, paged
rich hex firmware.bin --offset 0x200 --length 64        # hex dump (alias: hexdump)
rich unicode notes.txt                                  # graphemes, code points, widths
rich env PATH                                           # environment, secrets masked; PATH checked
rich capture --export-svg run.svg -- cargo test         # run a command and show/export its output
rich ansi explain capture.ans                           # decode every escape sequence
rich doctor                                             # what rich detected about this terminal
rich bench compare base.json new.json --threshold 10    # gate on benchmark regressions
rich completions bash                                   # shell completions; `rich docs man` for man pages
rich config explain width                               # where a setting comes from

This source is 0.0.12, prepared but not yet published (the latest published version is 0.0.11). It follows independent SemVer; its version does not mirror Python rich-cli. The tracked upstream release is rich-cli 1.8.1, recorded in UPSTREAM.toml.

Render modes

With no flag the mode is picked from the file extension; a bare - reads stdin. --format auto (the default) detects piped or extensionless input, and a named format (json, yaml, toml, xml, ini, env) overrides the extension. Preferred subcommands such as rich json, rich markdown, rich csv, rich jsonl and rich log are aliases over the same renderers. Mermaid has only a subcommand, rich mermaid (alias mmd); .mmd and .mermaid files are detected. Existing flat flags remain supported.

Options

Layout : -w/--width, --left/--center/--right, --panel BOX with --title/--caption/--style, --padding, --pager, --sanitize, --report json, --no-color. --auto-pager pages terminal output only when it exceeds the viewport height; --no-pager disables configured paging. Redirected stdout is never paged.

Export : --export-html PATH and --export-svg PATH also write a document, while the output still goes to the terminal — any render mode can be captured this way. The HTML is self-contained; the SVG loads its font from a CDN.

Watch : --watch re-renders changed local files (several may be given, each in its own live region) or one URL. Files use OS file events debounced by --watch-debounce SEC (default 0.1); --watch-poll polls every --watch-interval SEC instead, and URLs are always polled. --watch-exit-on-error stops on the first failed render. --watch-cache avoids re-rendering unchanged URL responses. Watch mode is intentionally finite when stdout is redirected: it renders one snapshot and exits, making pipelines deterministic. Builds without the fetch feature reject URL watches with the same stable URL-support error as one-shot URL input. Watch cannot be combined with batch or explicit/automatic paging.

Batch : --batch plans local files, directories and globs. --dry-run reports the plan and planning errors without writing outputs. --jobs N bounds subprocess workers for file exports; disk-spooled output is replayed in input order. Terminal-only batches remain serial. Fail-fast stops new scheduling while in-flight workers finish; --continue-on-error permits later scheduling. Human-report stderr terminals show completed/failed/total progress; --no-progress disables it. JSON reports and redirected stderr never contain progress. Ctrl+C stops scheduling, kills and reaps started workers and exits 130; completed exports may remain.

Configuration : --config PATH and --profile NAME select strict TOML defaults and profiles. Precedence is defaults, selected profile, then explicit CLI settings; profile false and inverse flags can disable inherited booleans. Unknown keys and invalid values fail even in inactive profiles. rich config show and rich config validate return JSON; settings includes configured values and explicit overrides, not every built-in default. --no-config disables config. [themes.NAME] maps style names to styles. Select with defaults/profile theme or --theme NAME; --theme-style NAME=STYLE overrides individual bindings. Workers inherit resolved bindings for consistent exports. --theme-file PATH (or theme_file) loads the [styles] section of an upstream rich theme file. rich config explain [KEY] shows which layer sets each value, and rich config reference lists every key.

Still-image crop : --image-fit contain|cover fits the image into an explicit height and bounded width. --image-fit native needs no height: it draws the image at its own pixel size, never enlarged, capped by the width and the terminal. --image-background '#RRGGBB' composites transparency; default leaves it to the terminal's background and checkerboard shows it on a gray checkerboard. With cover, --image-anchor selects center (default), top, bottom, left, right or a corner such as top-left. Contain stays centered.

Code highlighting : --highlighter syntect (the default) or lumis (a build with the lumis feature) picks the highlighter for source, Markdown code, view and diff. --code-theme NAME picks one of its themes; every highlighter has ansi_dark and ansi_light, which use the terminal's own 16 colours. rich doctor --report json lists the highlighters and themes.

Mermaid : rich mermaid FILE and ```mermaid fences in Markdown draw flowcharts as text. --mermaid-backend mmdc (a build with the mmdc feature) renders every diagram type through Mermaid's own CLI, which needs Node and a headless browser; off leaves fences as code.

Filter and highlight : --filter PATTERN keeps only what matches, and --highlight PATTERN marks matches in reverse video. For text, --print and --syntax the pattern is a regular expression over lines; with --inspect it is a JSONPath.

Image palette : --image-color ansi256|ansi16|grayscale opts ASCII, half-block, quadrant and Sixel still images, and GIF frames, into a fixed palette. Add --image-dither floyd-steinberg, bayer4x4 or atkinson for dithering, and --image-color-distance oklab to match colours perceptually. Truecolor/no-dither remains the default. Unsupported combinations are rejected: Braille is monochrome, and image diffs ignore these options.

Quadrants and adjustments : --image-mode quadrants draws 2×2 pixels per cell. --image-fit stretch ignores the aspect ratio; --image-max-width/--image-max-height cap the size; --image-brightness, --image-contrast and --image-gamma (1.0 = unchanged) adjust tone before quantization.

Discovery and diagnostics : --demo-list lists core, workflows, art; --demo --demo-section workflows plays one group. rich doctor inspects build, terminal, selected config and pager settings without terminal probes, network requests or pager execution. Its successful --report json document goes to stdout. Sixel capability is inferred, not tested.

Ask in a script : rich choose, rich filter, rich input, rich confirm and rich pager paint on stderr and answer on stdout, so x=$(rich choose a b c) works, and read keys from the terminal even when stdin is the list (ls | rich filter). --preview COMMAND shows a command's output for the focused item. Exit codes: 0 answered (or yes), 1 cancelled (or no), 130 Ctrl+C, 2 usage, 3 no answer without a terminal, where they degrade instead of waiting.

Viewers and capture : rich view sanitises terminal controls by default, as text rich diff does (--no-sanitize opts out). view, hex, unicode, inspect and capture read a bounded amount (see Limits). rich capture exits with the command's status; --cast FILE records an asciicast, and the experimental --redact / --redact-pattern mask secrets on a best-effort basis. rich COMMAND --help shows one command's options.

See the workflow recipes, the CLI reference and the 0.0.13 release notes. Source versions do not imply publication.

Features

These five are on by default and can be dropped for a smaller binary:

• fetch — URL support (rich <url>), via ureq with bundled TLS roots.
• art — --gif playback and --diff/--image picture rendering, via rs-rich-art.
• mermaid — rich mermaid and Mermaid fences in Markdown, drawn as text, via rs-rich-mermaid.
• record — rich record TAPE: scripted terminal sessions rendered as screenshots, casts, GIF and MP4, via rs-rich-record.
• interact — rich choose, filter, input, confirm and pager, via rs-rich-interact.

Off by default:

• lumis — the tree-sitter highlighter (--highlighter lumis), via rs-rich-lumis. It compiles many grammars, so the binary is much larger, and it needs Rust 1.91.
• mmdc — the mmdc Mermaid backend. It starts Mermaid's CLI, which must be installed separately.

cargo install rs-rich-cli --no-default-features   # installs `rich`; no network or image decoders

Licence

MIT.

Optional syntax cache

For repetitive source files, build the CLI with cargo build -p rs-rich-cli --release --features syntax-cache. This feature is off by default and changes no CLI flags. It reuses parsing work within one render; varied source files may see no speedup. See the measurements.

For faster highlighting of any source file, build with --features onig. That uses the Oniguruma regex engine (C, compiled from bundled source, so a C compiler is needed): 2–4× faster, with the same output. It is off by default.

Since 0.0.9 the CLI also has --log-presentation rich, still-image rotation/flips/grayscale and --image-dither bayer4x4, HTML/SVG still-image exports, and batch --batch-preserve-dirs, --batch-input-root, --batch-name-template. Run rich --help for accepted values; flags are opt-in. New batch naming modes treat export paths as directories, while legacy flat export naming is unchanged.