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 dot services.dot                                   # a DOT (Graphviz) graph, drawn as text
rich deps --why syn                                     # Cargo dependency tree; what pulls a crate in
rich schema order-v1.json order-v2.json                 # a JSON Schema as a tree, or what changed
rich schema --er shop.sql                               # SQL DDL (or Arrow) as an ER diagram
rich chart sales.csv --kind bar --x month --y revenue   # a chart from CSV, JSON or stdin
rich profile orders.csv --columns region,amount        # types, nulls, statistics, distributions
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
rich explore config.yaml                                # browse a document; Enter prints the path
rich micro list                                         # micro assets, drawn as this terminal can
rich record demo.tape                                   # run a scripted terminal recording

This source is 0.0.15, prepared but not yet published (the latest published version is 0.0.14). 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 and DOT have only subcommands, rich mermaid (alias mmd) and rich dot (alias graphviz); .mmd, .mermaid, .dot and .gv 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.

Diagram sources : rich dot FILE (alias graphviz; .dot and .gv files are detected) and ```dot fences draw DOT natively; a construct the parser does not support is refused with its line. --dot-backend graphviz --export-svg OUT.svg writes Graphviz's own SVG (the dot program), which a project's ./rich.toml cannot turn on. rich deps [MANIFEST] draws cargo metadata as a tree (--metadata FILE, --why CRATE, --graph, --depth N, --duplicates, --no-dev), and rich schema FILE [NEW] a JSON Schema, or what changed between two.

Charts : rich chart [FILE] draws CSV, TSV, JSON, JSON Lines or bare numbers (from a file, a URL or stdin) as a sparkline, bars, lines, points or a heatmap (--kind spark|bar|line|scatter|heatmap). --x COLUMN names the positions or labels and --y COLUMN, repeatable, the series; columns go by header or 1-based number. A missing column, or a value that is not a number, is refused with its row and column (exit 4).

Profiles : rich profile [FILE] profiles CSV, TSV or JSON Lines (from a file, a URL or stdin): each column's type, nulls, distinct values, statistics and a histogram or its most common values, and a map of where the nulls are. Input is streamed; past --sample N rows (10,000) the statistics describe a uniform sample and the heading prints its size. --columns a,b and --top N choose what is shown, and --report json writes the profile as JSON to stdout.

Schemas and inferred types : rich schema reads JSON Schema, SQL DDL (.sql, .ddl, or text starting with CREATE) and, with the arrow feature, Arrow IPC files; any two compare, and --er draws an ER diagram. --infer shows each --csv column's inferred type under its heading; without it the table is rich-cli's.

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 (and rich write, file, color, asset and explore) 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.14 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, and micro assets (rich micro, :micro:name: with --emoji), via rs-rich-micro.
• 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, pager, write, file, color, asset and explore, via rs-rich-interact.

rich dot, rich deps, rich schema and rich chart are in every build: DOT through rs-rich-diagram (with its plugin and graphviz features), the rest through rs-rich-ext.

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.
• arrow — rich schema reading Arrow IPC files and streams (.arrow, .feather, .arrows, .ipc), via rs-rich-data's Arrow adapter. It compiles the Arrow array and IPC crates.
• dylib-plugins, wasm-plugins — runtime plugins loaded with --plugin PATH or from a trusted config: native libraries, or sandboxed WASM modules.

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.