CLI reference

Every option the rich command accepts, taken from the binary's own --help so that this page cannot drift from it.

Looking for how to do something rather than what a flag is called? Start at Using the CLI.

rich 0.0.4 — Rust port of the rich-cli terminal toolbox

Usage

rich [OPTIONS] [RESOURCE]

RESOURCE is a file path, an http(s) URL, or `-` for stdin. Everything after a
bare `--` is a RESOURCE, however much it looks like an option. Input modes with
no RESOURCE read stdin until EOF; `-p -` reads markup from stdin too. Terminal
stdin shows an input hint. Repeated scalar options use their last value.

Render modes

Choose at most one; default auto-detects .md/.json/.csv/.tsv/.ipynb by extension — anything else with a file extension is syntax-highlighted.

-p, --print      Treat RESOURCE as literal markup TEXT, not a file path
-m, --markdown   Render RESOURCE as Markdown
-j, --json       Pretty-print RESOURCE as JSON
-x, --syntax     Syntax-highlight RESOURCE (language from its extension)
    --csv        Render RESOURCE as a CSV/TSV table
    --ipynb      Render RESOURCE as a Jupyter notebook
    --gif        Animate GIFs side by side; pipes receive the first frame
    --loop N     With --gif, repeat N times (default 1; 0 = forever)
    --rule       Draw a horizontal rule (RESOURCE is its title)
    --diff       Perceptually compare two images (needs exactly two)

Options

-w, --width N    Render the output N columns wide (the console keeps its
                 own width, so --left/--center/--right still use it)
    --image-mode M
                 With --diff, how to draw the picture: auto (default),
                 sixel (real pixels), blocks, ascii, none
    --gif-mode M With --gif: ascii (default) or blocks (half-block pixels).
                 Blocks fall back to ASCII without color or when piped.
    --encoding E Explicit text encoding: utf-8, utf-16 (BOM required),
                 utf-16le or utf-16be. Strict; files, stdin and URLs only.
    --threshold PCT
                 With --diff, exit non-zero above PCT% changed.
                 Also sets the exit code: 0 within, 1 over.
    --left       Left-justify output
    --center     Center output
    --right      Right-justify output
-o, --export-html PATH
                 Also write a self-contained HTML document to PATH
    --export-svg PATH
                 Also write an SVG document to PATH. Unlike the HTML,
                 it references its font from a CDN, so it is not
                 self-contained offline.
    --panel BOX  Wrap output in a panel, shrunk to fit its content
                 (ascii/ascii2/square/rounded/heavy/double; none = no panel)
    --padding P  Wrap output in padding (1, 2, or 4 comma-separated ints)
-e, --expand     Make --panel/--padding fill the width instead of fitting
                 (implied by --width)
    --title T    Panel title; also the CSV table's title
    --caption T  Panel subtitle; also the CSV table's caption
-y, --hyperlinks Render a Markdown link as a clickable OSC 8 hyperlink.
                 Off by default, which shows the URL as `text (url)`
-s, --style S    Style laid under the whole output, e.g. "bold red"
-S, --panel-style S
                 Panel border style, e.g. "dim" (with --panel)
    --pager      Page via MANPAGER, then PAGER, then less/more.com
    --no-color   Disable colored output (as does a non-empty NO_COLOR)
-h, --help       Show this help
-V, --version    Show the rs-rich-cli package version

Environment variables

NO_COLOR         Any non-empty value disables colour
COLUMNS          Console width (default 80 when unavailable)
MANPAGER, PAGER   Pager command; fallback is less (Unix), more.com (Windows)
FORCE_COLOR      Not supported; redirected stdout stays plain
RICH_SIXEL       0/1 overrides Sixel detection for --image-mode auto

With no RESOURCE and no mode flag, a capability demo is shown. Layout, style,
paging, hyperlinks and export options require a resource or render mode.

Exit codes

Code	Meaning
0	The resource rendered. With --diff --threshold, also: change was within the threshold.
1	The run failed: the resource could not be read or parsed, a flag was invalid or orphaned, or --diff --threshold found more change than allowed.

rich writes diagnostics to stderr and rendered output to stdout, so rich --csv data.csv > table.txt keeps the two apart.

A failure always exits non-zero

Earlier versions printed a fabricated table and exited 0 when a CSV's delimiter could not be determined. That is fixed: unreadable input now fails loudly, so rich --csv "$f" && publish no longer proceeds on garbage.