Every option the rich command accepts, generated from the same command
description as the binary's own --help (rich docs markdown and
rich docs config) 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.24 — Rust port of the rich-cli terminal toolbox
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.
A --no-… spelling (such as --no-watch) disables the corresponding config/default boolean.
Choose at most one; the default auto-detects .md/.rst/.json/.csv/.tsv/.ipynb, .mmd/.mermaid and .dot/.gv by extension, and .org, .adoc/.asciidoc and .man/.roff/.mdoc documents; a man page's section extension (.1 to .9) or .asc counts when the content agrees, and a file with no extension that is plainly Org, AsciiDoc or roff renders as one — anything else with a file extension is syntax-highlighted.
Option
Description
-p, --print
Treat RESOURCE as literal markup TEXT, not a file path.
-m, --markdown
Render RESOURCE as Markdown.
--rst
Render RESOURCE as reStructuredText.
--org
Render RESOURCE as an Org document (headlines, TODO keywords, lists, blocks, tables, drawers)
--asciidoc, --adoc
Render RESOURCE as AsciiDoc (sections, attributes, lists, source blocks with callouts, tables, admonitions)
--man, --roff
Render RESOURCE as a man page from its roff source (man and mdoc macros, tbl tables)
-j, -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.
--jsonl, --ndjson
Stream JSON Lines / NDJSON records.
--log
Stream log records: JSON Lines, logfmt and common text formats, filtered, followed and grouped.
--gif
Animate GIFs (and animated WebPs) side by side; pipes receive the first frame.
-u, --rule
Draw a horizontal rule (RESOURCE is its title)
--diff
Compare two images perceptually, two text files as a diff (syntax-aware; ANSI captures by visible text and style), or render one patch such as git diff output.
--image
Render RESOURCE (PNG, JPEG, GIF or WebP) as a still image (ASCII/Braille/blocks/quadrants/Sixel)
--inspect
Explore structured data (JSON, YAML, TOML, XML, INI, dotenv) as a tree.
--ansi-explain
Decode every escape sequence in RESOURCE and show the visible text.
Input format. With --inspect, the parser (default auto-detect); otherwise auto detects piped or extensionless input and routes it (JSON to --json, other formats to highlighting, likely Markdown, reStructuredText, Org, AsciiDoc and man pages to their renderers, anything else to plain text), and a named format overrides the extension. A document format (markdown, rst, org, asciidoc, man) is the same as its mode flag. Default: auto. Config: format. Possible values: auto, json, yaml, toml, xml, ini, env, markdown, rst, org, asciidoc, man.
--encoding <E>
Explicit text encoding: utf-8, utf-16 (BOM required), utf-16le or utf-16be. Strict; files, stdin and URLs only. Possible values: utf-8, utf-16, utf-16le, utf-16be.
Show the first LINES of a source file or CSV (as upstream, -h is --head, not help)
-t, --tail <LINES>
Show the end of a source file or CSV (as upstream, --tail N shows the last N-1 source lines)
-n, --line-numbers
Number the lines of source.
-g, --guides
Draw indentation guides in source.
--lexer <LEXER>
Highlight source as LEXER instead of guessing from the file name; with --rst, --org, --asciidoc or --man, highlight code blocks that name no language as LEXER.
--no-wrap
Crop long lines of source instead of wrapping them; with --print, don't wrap text.
--infer
With --csv (or a .csv/.tsv file), infer each column's type (integer, float, boolean, date, timestamp, text) and show it under the heading; number columns right-align even with null tokens such as NA. Without it the table is rich-cli's.
With --rule, the line's style. Default: bright_green.
--rule-char <CHARACTER>
With --rule, the character(s) the line is drawn with. Default: ─.
--log-presentation <MODE>
With --log, select log presentation. Default: plain. Config: log_presentation. Possible values: plain, rich.
--mermaid-backend <BACKEND>
How Mermaid diagrams (rich mermaid, ``mermaid fences in Markdown) are drawn: text draws flowcharts, sequence and ER diagrams as text, mmdc uses Mermaid's own CLI (a build with the mmdc feature;rich mermaidtries it first there), off leaves fences as code. Config:mermaid_backend. Possible values:text,mmdc,off`.
--dot-backend <BACKEND>
How DOT graphs (rich dot, ``dot fences in Markdown) are drawn: text draws them natively, graphviz also makes --export-svg write Graphviz's own SVG (thedotprogram, installed separately), off leaves fences as code. Config:dot_backend. Possible values:text,graphviz,off`.
--highlighter <NAME>
The code highlighter for source, Markdown code, view and diff: syntect (the default), or lumis in a build with the lumis feature. Config: highlighter.
--code-theme <NAME>
A theme of the chosen code highlighter, e.g. ansi_dark (rich doctor --report json lists them) Config: code_theme.
--loop <N>
With --gif, repeat N times (default 1; 0 = forever)
--speed <X>
With --gif, play X times as fast (0.5 = half speed; default 1)
--fps <N>
With --gif, draw at most N frames a second (default 30)
--max-frames <N>
With --gif, stop each animation after N frames, even with --loop 0.
--max-duration <SECS>
With --gif, stop after SECS seconds, whatever is still playing.
--gif-mode <M>
With --gif: ascii or blocks (half-block pixels). Blocks fall back to ASCII without color or when piped. Default: ascii. Possible values: ascii, blocks.
With rich deps, read cargo metadata --format-version 1 JSON from FILE (- for stdin) instead of running cargo.
--why <CRATE>
With rich deps, show what pulls CRATE (name or name@version) in: every path from the workspace to it.
--graph
With rich deps, draw the dependencies (or --why's paths) as a diagram instead of a tree.
--depth <N>
With rich deps, show at most N levels below each workspace member; with rich profile, profile JSON paths at most N steps deep (default 4), an object or array at the last step counting as its JSON text.
--duplicates
With rich deps, keep only the branches that lead to a crate resolved at more than one version, and add a consolidation summary: who pulls each version, and which version most of them already use.
--no-dev
With rich deps, leave dev-dependencies out.
--features
With rich deps, show the features Cargo resolved for each crate: what each turns on, and which dependents asked for them; every crate with a feature, or only --package's.
--package <CRATE>
With rich deps --features, show only CRATE, as name or name@version.
--timings <FILE>
With rich deps, show a cargo build --timings report (the HTML file, or timing-info JSON lines; - for stdin): the slowest units as bars and a table; runs nothing.
--audit <FILE>
With rich deps, show cargo audit --json output from FILE (- for stdin) grouped by severity; exits 5 when it lists a vulnerability. Runs no scanner.
--licenses
With rich deps, group the crates by licence, marking copyleft, unknown and missing licences.
--sizes
With rich deps, show artifact sizes per crate as bars and a table: from the target directory given next (default: the one cargo metadata names), matched to packages through cargo metadata, or from a file given next: cargo bloat --crates --message-format json output or a report saved with --save (- for stdin)
--build-profile <NAME>
With rich deps --sizes, read this profile's artifacts: debug (dev), release, or a custom profile (default: debug if it was built, else release)
--source-sizes
With rich deps --sizes, also add up each package's source files (its manifest directory, without target/, .git/ and nested packages)
--baseline <FILE>
With rich deps --timings or --sizes, compare with an older report, unit by unit (a report saved with --save, or the original format: a timings report, cargo-bloat JSON or a target directory); exits 5 when a unit or the total regressed past --threshold.
--save <FILE>
With rich deps --timings or --sizes, also write the report as JSON to FILE, to keep as a --baseline.
--policy <FILE>
With rich deps, check every crate's licence against a policy: a TOML allow and deny list, or cargo-deny's deny.toml; conflicts with the root crate's licence are shown too (a heuristic, not legal advice). Exits 5 on a violation.
--sbom <FILE>
With rich deps --licenses or --policy, read the packages from an SPDX (2.2, 2.3) or CycloneDX (1.4 to 1.6) JSON document instead of cargo metadata.
--er
With rich schema, draw the schema as an ER diagram: a box per table with its columns and keys, an edge per foreign key.
With rich chart, what to draw: spark (a sparkline per series), bar (a bar per row, labelled by --x), line (the default) and scatter (each series against --x, or the row number), heatmap (rows by series, each value a shade), pie (one series as slices, labelled by --x) or stacked (a bar per row, each series a part) Possible values: spark, bar, line, scatter, heatmap, pie, stacked.
--x <COLUMN>
With rich chart, the column of x positions (line, scatter) or labels (bar, heatmap, pie, stacked), by header or 1-based number (default: the row number; for labels, the first column that is not all numbers)
--y <COLUMN>...
With rich chart, a column to draw, by header or 1-based number; repeatable, one series each (default: every numeric column but --x)
With rich profile, the most rows kept for types, statistics and distributions (default 10000): a longer input is sampled uniformly, the sample size is printed, and nulls still count every row.
--columns <COLUMN[,COLUMN...]>...
With rich profile, profile only these columns, by header, in this order; repeatable.
--top <N>
With rich profile, the most common values shown for a column that is not numeric (default 5); with rich deps --sizes, --timings or --baseline, the units shown (default 20)
--max-paths <N>
With rich profile of JSON Lines, profile at most N paths (default 200), in the order first seen; the rest are noted.
--flat
With rich profile of JSON Lines, profile rows of the top-level keys (nested values as JSON text) instead of every nested path.
--style-rule <RULE>...
Style the cells, rows or columns of a data table by value: COLUMN OP VALUE:STYLE or COLUMN OP VALUE:row:STYLE (e.g. 'latency>500:bold red', 'status=failed:row:on red'); OP is == != < <= > >= *= ^= $= or a word such as contains or empty. Repeatable; applies to --csv, rich profile's table and rich inspect --table, and has no effect elsewhere. Config: rules.
--rules <FILE>...
Read style rules from FILE's [[rules]] tables (column, op, value, style, target), after the rules before it.
With rich log, keep only records at LEVEL (trace, debug, info, warn, error or fatal), or at it and above with a + (warn+); several with commas or by repeating it.
--where <EXPR>...
With rich log, keep only records whose fields pass EXPR: FIELD=VALUE, FIELD!=VALUE, FIELD>N (and >=, <, <=), FIELD~REGEX, FIELD!~REGEX, FIELD (it is there) or !FIELD (it is not); numbers, levels and times compare as such, dots reach nested fields; repeatable, and every one must pass.
-f, --follow
With rich log, read FILE, then what is appended to it, starting again when it is truncated or replaced (log rotation), until Ctrl+C.
--collapse, --no-collapse
With rich log, fold a run of identical records (their times aside) into the first and a × N count; on by default with --follow and --interactive.
--fields
With rich log, list each record's fields under it, one a line, instead of on its line.
--parser <NAME>
With rich log, how lines that are not JSON are read: auto tries each format; logfmt, level (LEVEL message), timestamp (a line that starts with a time) and access (nginx and Apache) read one; text reads none. A line no parser reads joins the record before it, or is shown as text. Default: auto. Possible values: auto, logfmt, level, timestamp, access, text.
--time <MODE>
With rich log, show each time as written (absolute), since the first record shown (relative), or not at all (none) Default: absolute. Possible values: absolute, relative, none.
--output <FORMAT>
With rich log, write the records kept as text, or as one JSON object a line (jsonl) for another program. Default: text. Possible values: text, jsonl.
--summary, --no-summary
With rich log, end with a summary: records shown, counts by level and, with --group, the groups with errors; on by default with --group (on standard error with --output jsonl)
-i, --interactive
With rich log on a terminal, show the records in a live view that follows the end: / filters, Space pauses, Enter shows a record's fields, q quits; without a terminal the records stream as usual.
With --diff/--image, how to draw the picture: sixel draws real pixels; blocks, quadrants, braille and ascii draw characters (--image rejects none: there would be nothing to draw) Default: auto. Possible values: auto, sixel, blocks, quadrants, braille, ascii, none.
--height <N>
With --image, render this many rows instead of the backend's default. Config: height.
--image-fit <M>
With --image and --height: contain letterboxes, cover crops at --image-anchor, stretch fills ignoring aspect. native needs no --height: it renders the image at its own pixel size (never enlarged), capped by --width, the terminal and --image-max-width/--image-max-height. Config: image_fit. Possible values: contain, cover, stretch, native.
--image-anchor <A>
Cover crop anchor. Default: center. Config: image_anchor. Possible values: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right.
--image-max-width <N>
With --image, never exceed N columns (aspect kept) Config: image_max_width.
--image-max-height <N>
With --image, never exceed N rows (aspect kept) Config: image_max_height.
--image-background <BG>
With --image: flatten transparency onto #RRGGBB (also colours contain padding; quote the # in your shell), leave it to the terminal's background (default), or show it on a gray checkerboard (checkerboard) Config: image_background.
--image-color <M>
Colour depth for --image (not Braille, which is monochrome) and --gif frames. Default: truecolor. Config: image_color. Possible values: truecolor, ansi256, ansi16, grayscale.
--image-dither <M>
Dithering (needs a non-truecolor --image-color) Default: none. Config: image_dither. Possible values: none, floyd-steinberg, bayer4x4, atkinson.
--image-color-distance <M>
How the nearest palette colour is measured: encoded RGB, or perceptual OKLab (needs a non-truecolor --image-color) Default: rgb. Config: image_color_distance. Possible values: rgb, oklab.
--image-brightness <F>
Tone adjustment (1.0 = unchanged). Brightness, contrast and gamma apply in that order, after rotation/flips and before grayscale and colour. Default: 1.0. Config: image_brightness.
--image-contrast <F>
Tone adjustment (1.0 = unchanged) Default: 1.0. Config: image_contrast.
--image-gamma <F>
Tone adjustment (1.0 = unchanged) Default: 1.0. Config: image_gamma.
--image-rotate <N>
Rotate still images clockwise. Default: 0. Config: image_rotate. Possible values: 0, 90, 180, 270.
Flip still images horizontally, after rotation. Config: image_flip_horizontal.
--image-flip-vertical, --no-image-flip-vertical
Flip still images vertically, after rotation. Config: image_flip_vertical.
--image-grayscale, --no-image-grayscale
Composite and convert still images to grayscale. Config: image_grayscale.
--threshold <PCT>
With --diff, exit non-zero above PCT% changed (pixels for images, lines for text). Also sets the exit code: 0 within, 5 over. With rich deps --baseline, what counts as a regression: a percentage (default 10%) and a floor the change must also pass, a time (0.5s, the default for --timings) or a size (64KiB, the default for --sizes); give it twice for both.
Show only what a JSONPath expression selects, e.g. $.servers[*].name.
--filter <PATTERN>
Keep only what matches: with --inspect, the values a JSONPath selects and the containers above them; for text, --print and --syntax, the lines a regular expression matches.
--highlight <PATTERN>
Highlight what matches, in reverse video: with --inspect, the tree lines a JSONPath selects; for text, --print and --syntax, the matches of a regular expression.
--transform <NAME>...
Apply a registered text transform, such as one a --plugin adds, to text, --print and --syntax; repeatable, applied in the order given, after --filter and before --highlight. rich plugins list shows the names.
--find <TEXT>
Search keys and values (case-insensitive), highlighting matches.
--flatten
Show path = value rows instead of a tree.
--table
Show records, or a path/value table, instead of a tree.
--max-depth <N>
Fold containers deeper than N levels.
--max-length <N>
Show at most N items per container.
--show-paths
Append each value's path.
--redact
Mask secret-looking keys such as password, token and api_key. With rich capture, mask secrets in the output before it is shown, exported or recorded: secret-named key=value values, bearer tokens, GitHub/GitLab/Slack/Stripe/npm/sk- tokens, AWS key ids, JWTs and URL passwords; with rich log, the same in each record's fields and lines. Capture redaction is experimental and best effort: check the output before sharing it.
--compare <PATH>
Show added, removed and changed values against another document.
With a text --diff, show old and new in two columns.
--conflicts
With --diff, show the merge conflicts left in one FILE: numbered, ours, base and theirs side by side when the width allows, with context; exits 0 either way and 4 when the markers do not parse.
--context <N>
With a text --diff, unchanged lines around each change. Default: 3.
--language <NAME>
With a text --diff, highlight as this language instead of guessing from the file name.
--ansi-inline
With --ansi-explain, mark escapes inline in the text instead of a table.
--escapes-only
With --ansi-explain, list only escape sequences, not text runs.
With rich view, highlight every case-insensitive match and mark its line; with rich hex, highlight a byte string: hex such as de ad or 0xDEAD, or quoted text such as '"PNG"'.
--no-line-numbers
With rich view, leave out the line-number gutter.
--offset <N>
With rich hex, start N bytes in (decimal or 0x hex)
--length <N>
With rich hex, show at most N bytes.
--bytes-per-line <N>
With rich hex, bytes on each line (default: fit the width, up to 16)
--group <N\|BY>
With rich hex, bytes per group (default 8); with rich log, group records by trace, span or correlation id (trace_id, span_id, correlation_id, request_id, ...) under a header each, with a summary at the end.
--limit <N>
With rich unicode, show at most N graphemes.
--show-secrets
With rich env, show values whose names look secret instead of masking them.
--cast <FILE>
With rich capture, also write an asciicast v2 recording (asciinema play FILE)
--redact-pattern <REGEX>...
With rich capture and rich log, also mask matches of REGEX (only its secret group when it has one); repeatable. Experimental: check the output before sharing it.
--redact-preview
With rich capture or rich log and --redact or --redact-pattern, show each match on its line, highlighted, with its rule and replacement, and a summary, instead of the output; write nothing (no cast, export or log output) and name on stderr what would have been written. The preview shows the secrets unmasked. With --report json, the findings as one JSON document on stdout.
Also write a self-contained HTML document to PATH. Config: export_html.
--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. Config: export_svg.
--export-png <PATH>
Also write a PNG image of the output to PATH: the terminal's width, rich's SVG export theme, in a window titled like the SVG's, drawn with an embedded DejaVu Sans Mono so it is the same on every machine (the png feature; not with --batch)
Select a named theme from config; --theme also finds installed themes. Config: theme.
--theme-style <NAME=STYLE>...
Override a theme binding; repeatable and worker-safe.
--theme-file <PATH>
Load styles from an upstream rich theme file ([styles] section); --theme and --theme-style override it. Config: theme_file.
--plugin <PATH>...
Load a runtime plugin: a WASM module (.wasm, sandboxed; the default wasm-plugins feature) or a native library (.so, .dylib, .dll, which runs its own code; a build with the dylib-plugins feature); repeatable. rich plugins list shows what is loaded. Config: plugins.
--micro-project, --no-micro-project
Load micro assets from the project's .rich/micro/ (off by default: a project's assets load only when you trust it; ./rich.toml cannot turn this on) Config: micro_project.
Disable colored output (as does a non-empty NO_COLOR) Environment: NO_COLOR. Config: no_color.
--color
Override a config no_color setting (pipes remain plain)
--sanitize, --no-sanitize
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there. Config: sanitize.
--report <F>
Emit a result/error envelope on stderr. Default: human. Possible values: human, json.
Show any file: Markdown, CSV, notebooks, images and patches rendered, source and data numbered and highlighted, binary as hex; paged, searchable with --search
hex, hexdump
Hex dump with offsets, byte groups and an ASCII panel (--search, --offset, --length)
unicode
Show graphemes, code points, UTF-8 bytes, widths and invalid sequences
env
List environment variables, secrets masked; rich env PATH checks each PATH entry
capture
Run rich capture -- COMMAND ARGS… and show or export its output (--cast FILE records it, --redact masks secrets), then exit with the command's status
mermaid, mmd
Draw a Mermaid diagram: flowcharts, sequence and ER diagrams as text, every type through mmdc where built in (.mmd and .mermaid files are detected)
dot, graphviz
Draw a DOT (Graphviz) graph as text (.dot and .gv files are detected); what the native parser does not support is refused with its line
deps
A Cargo dependency tree from cargo metadata, crates resolved at several versions marked; --why CRATE for what pulls a crate in, --graph to draw it; --features, --licenses, --policy FILE, --timings FILE, --sizes and --audit FILE for supply-chain reports, --baseline FILE to compare timings or sizes
schema
A JSON Schema, SQL DDL or Arrow schema as a tree: types, required markers, constraints, keys, $refs resolved; with two schemas (of any of these formats), what changed between them and which changes break; --er draws an ER diagram
chart
A chart from CSV, JSON or stdin: a sparkline, bars, lines, points, a heatmap, a pie or stacked bars; --x and --y pick the columns, a missing column or a value that is not a number is refused with its row and column
profile
A profile of CSV, TSV or JSON Lines: each column's type, nulls, distinct values, statistics and distribution, and a map of where the nulls are; a long input is sampled. --report json writes the profile as JSON to stdout
config
Show, validate, explain or document configuration
choose
Pick from ITEMs with a fuzzy-filtered list and print the choice; exits 1 when cancelled
filter
Type to filter ITEMs and print the choice; without a terminal, print the lines that match --value
input
Read one line with editing and history, and print it
confirm
Ask a yes-or-no question; exits 0 for yes and 1 for no
pager
Page FILE (or standard input), keeping its colours: arrows and Space scroll, / searches, q quits; without a terminal, write it out
write
Write several lines and print them: Enter starts a line, Ctrl+D submits, Esc cancels; without a terminal, print standard input
file
Browse from DIR (default .) and print the path picked: type to filter, → opens, ← goes up, Ctrl+T shows hidden files; without a terminal, print --selected
color
Pick a colour and print it: rich's named colours, the 256 palette (Tab), or hex and rgb typed in, with a live swatch
asset
Pick an emoji, a box style or a spinner, with a preview, and print it
explore
Explore a JSON, YAML, TOML, XML, INI or .env document: ← → fold, type to search, Ctrl+Y copies the path and Alt+Y the value (OSC 52), Enter prints the path; without a terminal, print the tree
date
Pick a date on a month grid, a time of day, or both, and print it as 2026-10-17, 14:30 or 2026-10-17 14:30; without a terminal, read one typed in
approve
Review ITEMs (or lines, or JSON Lines, on standard input) one by one or in bulk: a approves, r rejects, s skips (A, R, S ask for a reason), Space marks, Enter submits; prints one JSON line per item with its decision
jump
Jump to anything: one fuzzy box over files, Markdown headings (#), code symbols (@), commands (>) and recent places in DIRs, grouped by source with a preview; prints the place picked (path, path:line or the command)
completions
Print a shell completion script
docs
Print reference documentation generated from this help
bench
Compare benchmark runs
micro
Micro assets: emoji-sized images and animations written :micro:name: (with --emoji). List, show, preview, add, remove and create them; install packs
banner
Draw TEXT as a FIGlet banner: a font, a style or colour gradient, alignment and width fitting. Built with the art feature
shell
Shell integration: init prints a script with completions, OSC 133 prompt marks, OSC 7 and a status line after each command; status and link are its helpers
spin
Run a command with a spinner and a title until it exits, and exit with its status (like gum spin); without a terminal it just runs the command
console
Print the tracing events an intuiTUIve app sends from another terminal (like textual console): run the app with INTUITUIVE_CONSOLE=1
record
Run tapes (scripted terminal sessions: type, press and hold keys, wait for screen text, take screenshots) in a real terminal and write PNG, SVG and text screenshots, an asciinema cast, a GIF, an animated PNG (when asked), an MP4 (with FFmpeg) and an HTML page with a player; video has every screen update at the tape's frame rate, and Kitty, Sixel and iTerm2 images; --audio records the program's sound too; --check compares screenshots with committed ones instead
plugins
List the plugins this build has — built in, linked, and any --plugin PATH loads — with their source, version, ABI and capabilities
plugin
Find, install, update and check plugins and asset packs from the plugin marketplace: a signed index, every file checked by SHA-256; an installed, enabled WASM plugin loads on every run without --plugin, after its file is checked against the lockfile
doctor
Read-only build, terminal, config and pager diagnostics; --report json writes diagnostic data to stdout
With rich log, keep only records at LEVEL (trace, debug, info, warn, error or fatal), or at it and above with a + (warn+); several with commas or by repeating it.
--where <EXPR>...
With rich log, keep only records whose fields pass EXPR: FIELD=VALUE, FIELD!=VALUE, FIELD>N (and >=, <, <=), FIELD~REGEX, FIELD!~REGEX, FIELD (it is there) or !FIELD (it is not); numbers, levels and times compare as such, dots reach nested fields; repeatable, and every one must pass.
-f, --follow
With rich log, read FILE, then what is appended to it, starting again when it is truncated or replaced (log rotation), until Ctrl+C.
--collapse, --no-collapse
With rich log, fold a run of identical records (their times aside) into the first and a × N count; on by default with --follow and --interactive.
--fields
With rich log, list each record's fields under it, one a line, instead of on its line.
--parser <NAME>
With rich log, how lines that are not JSON are read: auto tries each format; logfmt, level (LEVEL message), timestamp (a line that starts with a time) and access (nginx and Apache) read one; text reads none. A line no parser reads joins the record before it, or is shown as text. Default: auto. Possible values: auto, logfmt, level, timestamp, access, text.
--time <MODE>
With rich log, show each time as written (absolute), since the first record shown (relative), or not at all (none) Default: absolute. Possible values: absolute, relative, none.
--output <FORMAT>
With rich log, write the records kept as text, or as one JSON object a line (jsonl) for another program. Default: text. Possible values: text, jsonl.
--summary, --no-summary
With rich log, end with a summary: records shown, counts by level and, with --group, the groups with errors; on by default with --group (on standard error with --output jsonl)
-i, --interactive
With rich log on a terminal, show the records in a live view that follows the end: / filters, Space pauses, Enter shows a record's fields, q quits; without a terminal the records stream as usual.
With rich hex, bytes per group (default 8); with rich log, group records by trace, span or correlation id (trace_id, span_id, correlation_id, request_id, ...) under a header each, with a summary at the end.
--redact-pattern <REGEX>...
With rich capture and rich log, also mask matches of REGEX (only its secret group when it has one); repeatable. Experimental: check the output before sharing it.
--redact-preview
With rich capture or rich log and --redact or --redact-pattern, show each match on its line, highlighted, with its rule and replacement, and a summary, instead of the output; write nothing (no cast, export or log output) and name on stderr what would have been written. The preview shows the secrets unmasked. With --report json, the findings as one JSON document on stdout.
Mask secret-looking keys such as password, token and api_key. With rich capture, mask secrets in the output before it is shown, exported or recorded: secret-named key=value values, bearer tokens, GitHub/GitLab/Slack/Stripe/npm/sk- tokens, AWS key ids, JWTs and URL passwords; with rich log, the same in each record's fields and lines. Capture redaction is experimental and best effort: check the output before sharing it.
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there.
With a text --diff, show old and new in two columns.
--conflicts
With --diff, show the merge conflicts left in one FILE: numbered, ours, base and theirs side by side when the width allows, with context; exits 0 either way and 4 when the markers do not parse.
--context <N>
With a text --diff, unchanged lines around each change. Default: 3.
--language <NAME>
With a text --diff, highlight as this language instead of guessing from the file name.
With --diff, exit non-zero above PCT% changed (pixels for images, lines for text). Also sets the exit code: 0 within, 5 over. With rich deps --baseline, what counts as a regression: a percentage (default 10%) and a floor the change must also pass, a time (0.5s, the default for --timings) or a size (64KiB, the default for --sizes); give it twice for both.
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there.
Input format. With --inspect, the parser (default auto-detect); otherwise auto detects piped or extensionless input and routes it (JSON to --json, other formats to highlighting, likely Markdown, reStructuredText, Org, AsciiDoc and man pages to their renderers, anything else to plain text), and a named format overrides the extension. A document format (markdown, rst, org, asciidoc, man) is the same as its mode flag. Default: auto. Possible values: auto, json, yaml, toml, xml, ini, env, markdown, rst, org, asciidoc, man.
Show only what a JSONPath expression selects, e.g. $.servers[*].name.
--filter <PATTERN>
Keep only what matches: with --inspect, the values a JSONPath selects and the containers above them; for text, --print and --syntax, the lines a regular expression matches.
--highlight <PATTERN>
Highlight what matches, in reverse video: with --inspect, the tree lines a JSONPath selects; for text, --print and --syntax, the matches of a regular expression.
--transform <NAME>...
Apply a registered text transform, such as one a --plugin adds, to text, --print and --syntax; repeatable, applied in the order given, after --filter and before --highlight. rich plugins list shows the names.
--find <TEXT>
Search keys and values (case-insensitive), highlighting matches.
--flatten
Show path = value rows instead of a tree.
--table
Show records, or a path/value table, instead of a tree.
--max-depth <N>
Fold containers deeper than N levels.
--max-length <N>
Show at most N items per container.
--show-paths
Append each value's path.
--redact
Mask secret-looking keys such as password, token and api_key. With rich capture, mask secrets in the output before it is shown, exported or recorded: secret-named key=value values, bearer tokens, GitHub/GitLab/Slack/Stripe/npm/sk- tokens, AWS key ids, JWTs and URL passwords; with rich log, the same in each record's fields and lines. Capture redaction is experimental and best effort: check the output before sharing it.
--compare <PATH>
Show added, removed and changed values against another document.
Show any file: Markdown, CSV, notebooks, images and patches rendered, source and data numbered and highlighted, binary as hex; paged, searchable with --search
With rich view, highlight every case-insensitive match and mark its line; with rich hex, highlight a byte string: hex such as de ad or 0xDEAD, or quoted text such as '"PNG"'.
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there.
With rich view, highlight every case-insensitive match and mark its line; with rich hex, highlight a byte string: hex such as de ad or 0xDEAD, or quoted text such as '"PNG"'.
--offset <N>
With rich hex, start N bytes in (decimal or 0x hex)
--length <N>
With rich hex, show at most N bytes.
--bytes-per-line <N>
With rich hex, bytes on each line (default: fit the width, up to 16)
--group <N\|BY>
With rich hex, bytes per group (default 8); with rich log, group records by trace, span or correlation id (trace_id, span_id, correlation_id, request_id, ...) under a header each, with a summary at the end.
With rich capture, also write an asciicast v2 recording (asciinema play FILE)
--redact-pattern <REGEX>...
With rich capture and rich log, also mask matches of REGEX (only its secret group when it has one); repeatable. Experimental: check the output before sharing it.
--redact-preview
With rich capture or rich log and --redact or --redact-pattern, show each match on its line, highlighted, with its rule and replacement, and a summary, instead of the output; write nothing (no cast, export or log output) and name on stderr what would have been written. The preview shows the secrets unmasked. With --report json, the findings as one JSON document on stdout.
Mask secret-looking keys such as password, token and api_key. With rich capture, mask secrets in the output before it is shown, exported or recorded: secret-named key=value values, bearer tokens, GitHub/GitLab/Slack/Stripe/npm/sk- tokens, AWS key ids, JWTs and URL passwords; with rich log, the same in each record's fields and lines. Capture redaction is experimental and best effort: check the output before sharing it.
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there.
How Mermaid diagrams (rich mermaid, ``mermaid fences in Markdown) are drawn: text draws flowcharts, sequence and ER diagrams as text, mmdc uses Mermaid's own CLI (a build with the mmdc feature;rich mermaidtries it first there), off leaves fences as code. Possible values:text,mmdc,off`.
How DOT graphs (rich dot, ``dot fences in Markdown) are drawn: text draws them natively, graphviz also makes --export-svg write Graphviz's own SVG (thedotprogram, installed separately), off leaves fences as code. Possible values:text,graphviz,off`.
A Cargo dependency tree from cargo metadata, crates resolved at several versions marked; --why CRATE for what pulls a crate in, --graph to draw it; --features, --licenses, --policy FILE, --timings FILE, --sizes and --audit FILE for supply-chain reports, --baseline FILE to compare timings or sizes
With rich deps, read cargo metadata --format-version 1 JSON from FILE (- for stdin) instead of running cargo.
--why <CRATE>
With rich deps, show what pulls CRATE (name or name@version) in: every path from the workspace to it.
--graph
With rich deps, draw the dependencies (or --why's paths) as a diagram instead of a tree.
--depth <N>
With rich deps, show at most N levels below each workspace member; with rich profile, profile JSON paths at most N steps deep (default 4), an object or array at the last step counting as its JSON text.
--duplicates
With rich deps, keep only the branches that lead to a crate resolved at more than one version, and add a consolidation summary: who pulls each version, and which version most of them already use.
--no-dev
With rich deps, leave dev-dependencies out.
--features
With rich deps, show the features Cargo resolved for each crate: what each turns on, and which dependents asked for them; every crate with a feature, or only --package's.
--package <CRATE>
With rich deps --features, show only CRATE, as name or name@version.
--timings <FILE>
With rich deps, show a cargo build --timings report (the HTML file, or timing-info JSON lines; - for stdin): the slowest units as bars and a table; runs nothing.
--audit <FILE>
With rich deps, show cargo audit --json output from FILE (- for stdin) grouped by severity; exits 5 when it lists a vulnerability. Runs no scanner.
--licenses
With rich deps, group the crates by licence, marking copyleft, unknown and missing licences.
--sizes
With rich deps, show artifact sizes per crate as bars and a table: from the target directory given next (default: the one cargo metadata names), matched to packages through cargo metadata, or from a file given next: cargo bloat --crates --message-format json output or a report saved with --save (- for stdin)
--build-profile <NAME>
With rich deps --sizes, read this profile's artifacts: debug (dev), release, or a custom profile (default: debug if it was built, else release)
--source-sizes
With rich deps --sizes, also add up each package's source files (its manifest directory, without target/, .git/ and nested packages)
--top <N>
With rich profile, the most common values shown for a column that is not numeric (default 5); with rich deps --sizes, --timings or --baseline, the units shown (default 20)
--baseline <FILE>
With rich deps --timings or --sizes, compare with an older report, unit by unit (a report saved with --save, or the original format: a timings report, cargo-bloat JSON or a target directory); exits 5 when a unit or the total regressed past --threshold.
--threshold <PCT>
With --diff, exit non-zero above PCT% changed (pixels for images, lines for text). Also sets the exit code: 0 within, 5 over. With rich deps --baseline, what counts as a regression: a percentage (default 10%) and a floor the change must also pass, a time (0.5s, the default for --timings) or a size (64KiB, the default for --sizes); give it twice for both.
--save <FILE>
With rich deps --timings or --sizes, also write the report as JSON to FILE, to keep as a --baseline.
--policy <FILE>
With rich deps, check every crate's licence against a policy: a TOML allow and deny list, or cargo-deny's deny.toml; conflicts with the root crate's licence are shown too (a heuristic, not legal advice). Exits 5 on a violation.
--sbom <FILE>
With rich deps --licenses or --policy, read the packages from an SPDX (2.2, 2.3) or CycloneDX (1.4 to 1.6) JSON document instead of cargo metadata.
A JSON Schema, SQL DDL or Arrow schema as a tree: types, required markers, constraints, keys, $refs resolved; with two schemas (of any of these formats), what changed between them and which changes break; --er draws an ER diagram
A JSON Schema, SQL DDL (.sql, .ddl, or text starting with CREATE) or Arrow IPC file (.arrow, .feather, .arrows, .ipc; the arrow feature), an http(s) URL, or - for stdin.
[NEW_SCHEMA]
A second version: show what changed from SCHEMA to it.
A chart from CSV, JSON or stdin: a sparkline, bars, lines, points, a heatmap, a pie or stacked bars; --x and --y pick the columns, a missing column or a value that is not a number is refused with its row and column
With rich chart, what to draw: spark (a sparkline per series), bar (a bar per row, labelled by --x), line (the default) and scatter (each series against --x, or the row number), heatmap (rows by series, each value a shade), pie (one series as slices, labelled by --x) or stacked (a bar per row, each series a part) Possible values: spark, bar, line, scatter, heatmap, pie, stacked.
--x <COLUMN>
With rich chart, the column of x positions (line, scatter) or labels (bar, heatmap, pie, stacked), by header or 1-based number (default: the row number; for labels, the first column that is not all numbers)
--y <COLUMN>...
With rich chart, a column to draw, by header or 1-based number; repeatable, one series each (default: every numeric column but --x)
A profile of CSV, TSV or JSON Lines: each column's type, nulls, distinct values, statistics and distribution, and a map of where the nulls are; a long input is sampled. --report json writes the profile as JSON to stdout
With rich profile, the most rows kept for types, statistics and distributions (default 10000): a longer input is sampled uniformly, the sample size is printed, and nulls still count every row.
--columns <COLUMN[,COLUMN...]>...
With rich profile, profile only these columns, by header, in this order; repeatable.
--top <N>
With rich profile, the most common values shown for a column that is not numeric (default 5); with rich deps --sizes, --timings or --baseline, the units shown (default 20)
--depth <N>
With rich profile of JSON Lines, profile paths at most N steps deep (default 4), a key or [] each; an object or array at the last step counts as its JSON text.
--max-paths <N>
With rich profile of JSON Lines, profile at most N paths (default 200), in the order first seen; the rest are noted.
--flat
With rich profile of JSON Lines, profile rows of the top-level keys (nested values as JSON text) instead of every nested path.
--style-rule <RULE>...
Style the cells, rows or columns of a data table by value: COLUMN OP VALUE:STYLE or COLUMN OP VALUE:row:STYLE (e.g. 'latency>500:bold red', 'status=failed:row:on red'); OP is == != < <= > >= *= ^= $= or a word such as contains or empty. Repeatable; applies to --csv, rich profile's table and rich inspect --table, and has no effect elsewhere.
--rules <FILE>...
Read style rules from FILE's [[rules]] tables (column, op, value, style, target), after the rules before it.
Show, validate, explain or document configuration.
Each subcommand accepts --config PATH, --profile NAME, --no-config, --theme NAME and the setting flags (--width, --pager, ...) that rich itself accepts, as command-line overrides.
Pick several: Tab marks, Enter returns the marked items, one per line.
--selected <ITEM>...
Focus ITEM (with --multi, mark it); the answer without a terminal.
--height <ROWS>
Show at most ROWS items at once (default 10), fewer when the terminal is shorter.
--preview <COMMAND>
Show COMMAND's output for the focused item beside the list; {} is the item, shell-quoted, and $COLUMNS the pane's width (e.g. rich {} --force-terminal)
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
Pick several: Tab marks, Enter returns the marked items, one per line.
--selected <ITEM>...
Focus ITEM (with --multi, mark it); the answer without a terminal.
--height <ROWS>
Show at most ROWS items at once (default 10), fewer when the terminal is shorter.
--preview <COMMAND>
Show COMMAND's output for the focused item beside the list; {} is the item, shell-quoted, and $COLUMNS the pane's width (e.g. rich {} --force-terminal)
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
Browse from DIR (default .) and print the path picked: type to filter, → opens, ← goes up, Ctrl+T shows hidden files; without a terminal, print --selected
Show at most ROWS at once (default 10), fewer when the terminal is shorter.
--value <QUERY>
Start with QUERY typed.
--selected <PATH>
The answer without a terminal.
--all
Show hidden files to begin with.
--directory
Pick directories (files are not listed, unless --file is given too: then either)
--file
Pick files (the default)
--extension <EXT>...
List only files ending in .EXT (repeatable, or comma-separated)
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
Start with TEXT typed: a name to filter by, or a colour.
--default <COLOR>
The answer without a terminal, and to an empty line.
--format <FORMAT>
How to print it: #rrggbb (default), a rich name, or rgb(r,g,b) Possible values: hex, name, rgb.
--height <ROWS>
Show at most ROWS at once (default 10), fewer when the terminal is shorter.
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
What to pick (default emoji): an emoji prints as itself, a box style, spinner or micro asset by name. Possible values: emoji, box, spinner, micro.
--header <TEXT>
The prompt above the list.
--height <ROWS>
Show at most ROWS at once (default 10), fewer when the terminal is shorter.
--value <QUERY>
Start with QUERY typed.
--selected <NAME>
Focus NAME; the answer without a terminal and to an empty line.
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
--micro-project
With --kind micro, list the project's ./.rich/micro/ assets too (trust it)
Explore a JSON, YAML, TOML, XML, INI or .env document: ← → fold, type to search, Ctrl+Y copies the path and Alt+Y the value (OSC 52), Enter prints the path; without a terminal, print the tree
The document's format (default auto: from the file name, then the content), as for --inspect. Possible values: auto, json, yaml, toml, xml, ini, env.
--header <TEXT>
The prompt above the tree (default the file name)
--height <ROWS>
Show at most ROWS at once (default 10), fewer when the terminal is shorter.
--value <QUERY>
Start with QUERY searched.
--print <WHAT>
What Enter prints: the node's JSONPath (default), or its value (a string as it is, anything else as JSON) Possible values: path, value.
--icons
Mark true, false and null values with the status/success, status/error and status/info micro assets (drawn as the terminal can, or their emoji)
--mouse
Report the mouse: click a row to focus it and again to pick it, drag the border beside a preview (off by default: it takes text selection from the terminal)
Review ITEMs (or lines, or JSON Lines, on standard input) one by one or in bulk: a approves, r rejects, s skips (A, R, S ask for a reason), Space marks, Enter submits; prints one JSON line per item with its decision
How items are read: one per line, or a JSON object per line (default auto: JSON Lines when every line is an object) Possible values: auto, lines, jsonl.
--label <FIELD>
The JSON field to show as an item's label (default the first of title, name, label, summary and id)
--require-reason
Ask for a reason on every rejection, and refuse an empty one.
--auto-submit
Submit as soon as nothing is pending, without Enter.
--print <WHAT>
What to print: a JSON line per item with its decision and reason (default), or the approved (or rejected) items as they were read. Possible values: decisions, approved, rejected.
--height <ROWS>
Show at most ROWS at once, fewer when the terminal is shorter.
--mouse
Report the mouse: click rows and buttons, scroll with the wheel (off by default: it takes text selection from the terminal)
Jump to anything: one fuzzy box over files, Markdown headings (#), code symbols (@), commands (>) and recent places in DIRs, grouped by source with a preview; prints the place picked (path, path:line or the command)
Search code symbols: functions, types, classes and modules, found by their keywords.
--commands <FILE>
Search the commands in FILE, one per line (LABEL<TAB>COMMAND or just the command); a pick prints the command.
--recent <FILE>
Show FILE's places first, as Recent, and add the pick to it (the latest 50 kept)
--value <QUERY>
Start with QUERY typed; without a terminal, print its best match.
--limit <N>
Results each source shows until Tab narrows to it (default 5)
--print <WHAT>
What to print: the place (default), a JSON object with its source, label and place, or a shell command, safely quoted: cd -- 'DIR', ${EDITOR:-vi} [+LINE] -- 'FILE', or a > command as it is. Possible values: location, json, shell.
--height <ROWS>
Show at most ROWS at once, fewer when the terminal is shorter.
--mouse
Report the mouse: click rows and buttons, scroll with the wheel (off by default: it takes text selection from the terminal)
Every asset that resolves, drawn, with its size, kind, layer and alt text
show
One asset: its metadata, fallbacks, files and how its name resolved
preview
Draw an asset inline, as this terminal shows it, and magnified at the terminal's cell size; a package path or an image file (run through the pipeline) works too
add
Copy a package (a folder or .richmicro file) into the user layer
remove
Delete an asset's package from the user layer
create
Run an image (PNG, APNG, GIF, JPEG or WebP) through the pipeline and write a package the registry accepts
install
Install a pack (a folder or zip with pack.json) into the user layer
uninstall
Remove an installed pack by name from the user layer
Draw an asset inline, as this terminal shows it, and magnified at the terminal's cell size; a package path or an image file (run through the pipeline) works too
standard (bundled, the default), a FIGfont .flf file, or the name of one in $FIGLET_FONTDIR, /usr/share/figlet or /usr/local/share/figlet.
--list-fonts
List the bundled font and the .flf fonts found in those directories, then exit.
--style <STYLE>
A style for every row, such as bold cyan or white on blue.
--gradient <COLORS>
Colour the strokes along a gradient: two or more comma-separated colours (#ff0000,blue), or a preset: rainbow, sunset, ocean, forest, fire. Overrides --style's colour.
--direction <D>
Which way --gradient runs (default horizontal) Possible values: horizontal, vertical, diagonal.
--align <A>
Position the banner within the width (default left) Possible values: left, center, right.
-w, --width <N>
Lay the banner out to N columns (default: the terminal's width)
--fit <F>
When the banner is wider than the width: wrap it at spaces onto more rows (the default, as figlet does), print TEXT as plain text instead (plain), or let it overflow (none) Possible values: wrap, plain, none.
--effect <E>
Animate the banner: glow (the default when animating: a band of blue-green light travels through dark letters), shimmer, typewriter, fade, or still. It plays once (about 2 s), then holds the still final frame; any key skips to it. Not combined with --style or --gradient. Possible values: glow, shimmer, typewriter, fade, still.
--once
Play the animation once, then hold still (the default)
--loop
Play the animation again and again, until a key is pressed (or Ctrl+C)
--duration <SECS>
How long one play of the animation lasts (default 2, up to 60)
--wave
Animate, with a wave line under the banner.
--specks
Animate, with specks of light (·∘°) rising around the letters and a row above them.
--seed <N>
Where the specks start (default 0): the same seed draws the same specks.
--force-terminal
Write colour and styles even when stdout is not a terminal (for a pager or a file)
Shell integration: init prints a script with completions, OSC 133 prompt marks, OSC 7 and a status line after each command; status and link are its helpers
Run tapes (scripted terminal sessions: type, press and hold keys, wait for screen text, take screenshots) in a real terminal and write PNG, SVG and text screenshots, an asciinema cast, a GIF, an animated PNG (when asked), an MP4 (with FFmpeg) and an HTML page with a player; video has every screen update at the tape's frame rate, and Kitty, Sixel and iTerm2 images; --audio records the program's sound too; --check compares screenshots with committed ones instead
Set Framerate N: video frames a second, 1 to 60 (12); --fps overrides it
Set FontSize N: the text size of video frames, in pixels (16)
KeyDown KEY, KeyUp KEY: hold a key (Up, Ctrl+F, or one character) down, let it go; it autorepeats meanwhile (Set KeyRepeat DELAY INTERVAL, 200ms 33ms)
Hold KEY DURATION: KeyDown, wait, KeyUp
Set KittyKeyboard on: report the kitty keyboard protocol, so a program can turn it on and hear releases
Output gif png: write only these formats; without an Output line, every format but the APNG
Output apng (or --format apng, or all): an animated PNG beside (or instead of) the GIF; it is written only when asked
Set Audio on (or --audio): record the program's sound, which it writes to the directory in RICH_RECORD_AUDIO (intuiTUIve's audio outputs do); an MP4 carries it as AAC, the other outputs get a WAV beside them (off)
Find, install, update and check plugins and asset packs from the plugin marketplace: a signed index, every file checked by SHA-256; an installed, enabled WASM plugin loads on every run without --plugin, after its file is checked against the lockfile
List the marketplace's packages, or those with every word of QUERY in their id, name, description, keywords, authors or capabilities; the tier shows as ✓ official, approved or community, a maintainers' pick as ★ recommended, and who authored each
info
One package: its tier, source, versions, what loads here, for a crate the cargo add line, and its downloads, 👍/👎 and reviews link when the marketplace's stats.json is there (not signed, shown only)
install
Show the tier, permissions and capabilities, ask, then download, check (size, SHA-256, the WASM manifest in the sandbox) and install; a crate is refused with its cargo add line
update
Move installed packages (or those named) to the newest version this host loads, asking first; a yanked version is replaced
remove
Uninstall packages: the lockfile entry, then the file
list
What is installed: version, kind, tier, enabled, whether the file still matches the lockfile, and yank reasons last seen; no network
enable
Load an installed package again on every run
disable
Keep a package installed but do not load it
verify
Check every installed file against the lockfile, and every installed version against the current index; yanked versions are reported with their reason; exits 4 when a file or listing does not match
browse
The marketplace in a selector, with each package's provenance (tier, source, hash, permissions) beside the list; Enter installs, updates, removes, enables or disables
publish
Check a local package (a WASM plugin, a micro pack or a theme), compute its SHA-256 and size, and write its listing JSON for a pull request to the marketplace repository; no network
The marketplace's own site, https://buchochelliq-labs.github.io/rs-rich-marketplace/, searches and filters the same signed index in a browser; so does the docs site's Marketplace page, https://buchochelliq-labs.github.io/rs-rich-cli/latest/marketplace/. Both only show it: rich plugin install checks the signature.
List the marketplace's packages, or those with every word of QUERY in their id, name, description, keywords, authors or capabilities; the tier shows as ✓ official, approved or community, a maintainers' pick as ★ recommended, and who authored each
Only this kind: crate, wasm-plugin, micro-pack or theme.
--tier <TIER>
Only this tier: official (rs-rich's own), reviewed (shown as approved) or community.
--recommended
Only the maintainers' picks, marked ★ recommended.
--sort <ORDER>
id (the default), or downloads: most downloaded first, from the marketplace's unsigned stats.json, with a Downloads column.
--marketplace <LOCATION>
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
One package: its tier, source, versions, what loads here, for a crate the cargo add line, and its downloads, 👍/👎 and reviews link when the marketplace's stats.json is there (not signed, shown only)
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
Show the tier, permissions and capabilities, ask, then download, check (size, SHA-256, the WASM manifest in the sandbox) and install; a crate is refused with its cargo add line
Install without asking (for scripts); the summary is still shown.
--marketplace <LOCATION>
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
Install without asking (for scripts); the summary is still shown.
--marketplace <LOCATION>
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
Check every installed file against the lockfile, and every installed version against the current index; yanked versions are reported with their reason; exits 4 when a file or listing does not match
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
The marketplace in a selector, with each package's provenance (tier, source, hash, permissions) beside the list; Enter installs, updates, removes, enables or disables
The marketplace: an https:// base URL, or a directory or file:// URL laid out as the marketplace repository is (artifacts from its artifacts/HOST/PATH mirror, never the network); else RICH_MARKETPLACE, else the official one.
--marketplace-keys <FILE>
Trust this keys-N.json instead of the keys compiled in; else RICH_MARKETPLACE_KEYS.
--plugin-dir <DIR>
Install into DIR; else RICH_PLUGIN_DIR, else $XDG_DATA_HOME/rich/plugins (~/.local/share/rich/plugins)
--report <FORMAT>
json: the result or error envelope on stderr, nothing on stdout.
Check a local package (a WASM plugin, a micro pack or a theme), compute its SHA-256 and size, and write its listing JSON for a pull request to the marketplace repository; no network
Settings are TOML: version = 1, a [defaults] table, optional [profile.NAME] tables and [themes.NAME] style tables. rich config explain shows where each effective value comes from.
Settings are read from these sources, lowest precedence first; a later source overrides an earlier one:
defaults — Built-in defaults
environment (NO_COLOR) — A non-empty value sets no_color = true. A no_color = false in ./rich.toml cannot undo it; ~/.config/rich/config.toml, --config PATH and --color can
config file (./rich.toml, else ~/.config/rich/config.toml) — The [defaults] table. Only the first file found is read; --config PATH reads that file instead and --no-config reads none
profile ([profile.NAME]) — The profile selected with --profile (default: default) overrides the [defaults] table
command line — Explicit flags override every other source
Render mode, as the flag or command of the same name
format
enum: auto, json, yaml, toml, xml, ini, env, markdown, rst, org, asciidoc, man
auto
--format
Input format. With --inspect, the parser (default auto-detect); otherwise auto detects piped or extensionless input and routes it (JSON to --json, other formats to highlighting, likely Markdown, reStructuredText, Org, AsciiDoc and man pages to their renderers, anything else to plain text), and a named format overrides the extension. A document format (markdown, rst, org, asciidoc, man) is the same as its mode flag
width
positive integer
--width
Render the output N columns wide (the console keeps its own width, so --left/--center/--right still use it)
Wrap output in a panel, shrunk to fit its content (none = no panel)
padding
string
--padding
Wrap output in padding (1, 2, or 4 comma-separated ints)
log_presentation
enum: plain, rich
plain
--log-presentation
With --log, select log presentation
mermaid_backend
enum: text, mmdc, off
--mermaid-backend
How Mermaid diagrams (rich mermaid, ``mermaid fences in Markdown) are drawn: text draws flowcharts, sequence and ER diagrams as text, mmdc uses Mermaid's own CLI (a build with the mmdc feature;rich mermaid` tries it first there), off leaves fences as code
dot_backend
enum: text, graphviz, off
--dot-backend
How DOT graphs (rich dot, ``dot fences in Markdown) are drawn: text draws them natively, graphviz also makes --export-svg write Graphviz's own SVG (thedot` program, installed separately), off leaves fences as code
rules
array of rule tables
--style-rule
Style the cells, rows or columns of a data table by value: COLUMN OP VALUE:STYLE or COLUMN OP VALUE:row:STYLE (e.g. 'latency>500:bold red', 'status=failed:row:on red'); OP is == != < <= > >= *= ^= $= or a word such as contains or empty. Repeatable; applies to --csv, rich profile's table and rich inspect --table, and has no effect elsewhere
highlighter
string
--highlighter
The code highlighter for source, Markdown code, view and diff: syntect (the default), or lumis in a build with the lumis feature
code_theme
string
--code-theme
A theme of the chosen code highlighter, e.g. ansi_dark (rich doctor --report json lists them)
height
positive integer
--height
With --image, render this many rows instead of the backend's default
image_fit
enum: contain, cover, stretch, native
--image-fit
With --image and --height: contain letterboxes, cover crops at --image-anchor, stretch fills ignoring aspect. native needs no --height: it renders the image at its own pixel size (never enlarged), capped by --width, the terminal and --image-max-width/--image-max-height
image_anchor
enum: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right
center
--image-anchor
Cover crop anchor
image_max_width
positive integer
--image-max-width
With --image, never exceed N columns (aspect kept)
image_max_height
positive integer
--image-max-height
With --image, never exceed N rows (aspect kept)
image_background
string
--image-background
With --image: flatten transparency onto #RRGGBB (also colours contain padding; quote the # in your shell), leave it to the terminal's background (default), or show it on a gray checkerboard (checkerboard)
image_color
enum: truecolor, ansi256, ansi16, grayscale
truecolor
--image-color
Colour depth for --image (not Braille, which is monochrome) and --gif frames
image_dither
enum: none, floyd-steinberg, bayer4x4, atkinson
none
--image-dither
Dithering (needs a non-truecolor --image-color)
image_color_distance
enum: rgb, oklab
rgb
--image-color-distance
How the nearest palette colour is measured: encoded RGB, or perceptual OKLab (needs a non-truecolor --image-color)
image_brightness
number
1.0
--image-brightness
Tone adjustment (1.0 = unchanged). Brightness, contrast and gamma apply in that order, after rotation/flips and before grayscale and colour
image_contrast
number
1.0
--image-contrast
Tone adjustment (1.0 = unchanged)
image_gamma
number
1.0
--image-gamma
Tone adjustment (1.0 = unchanged)
image_rotate
enum: 0, 90, 180, 270
0
--image-rotate
Rotate still images clockwise
image_flip_horizontal
bool
--image-flip-horizontal
Flip still images horizontally, after rotation
image_flip_vertical
bool
--image-flip-vertical
Flip still images vertically, after rotation
image_grayscale
bool
--image-grayscale
Composite and convert still images to grayscale
export_html
path
--export-html
Also write a self-contained HTML document to PATH
export_svg
path
--export-svg
Also write an SVG document to PATH. Unlike the HTML, it references its font from a CDN, so it is not self-contained offline.
pager
bool
--pager
Page terminal output via MANPAGER, PAGER, then less/more.com
auto_pager
bool
--auto-pager
Page only terminal output taller than the viewport
watch
bool
--watch
Re-render changing files (several allowed) or one URL while stdout is a terminal; each file gets its own live region
watch_interval
number
1
--watch-interval
Poll interval in seconds
watch_debounce
number
0.1
--watch-debounce
Quiet period collapsing a burst of file events
watch_poll
bool
--watch-poll
Poll local files at --watch-interval instead of file events
watch_exit_on_error
bool
--watch-exit-on-error
End the watch with a non-zero exit when a render fails
watch_cache
bool
--watch-cache
With URLs, render only when the response body changes
batch
bool
--batch
Convert explicit files, directories, or globs deterministically
batch_input_root
path
--batch-input-root
The directory --batch-preserve-dirs keeps paths relative to
batch_preserve_dirs
bool
--batch-preserve-dirs
Preserve paths under --batch-input-root PATH
batch_name_template
string
--batch-name-template
Name export leaves; export paths become directories
jobs
positive integer
1
--jobs
Parallel file-export workers; requires --batch. Terminal output stays in input order; active jobs finish on error.
progress
bool
true
--progress
Enable/disable batch counts on terminal stderr; hidden for redirected stderr, JSON reports and dry runs
continue_on_error
bool
--continue-on-error
Process all planned inputs and aggregate failures
overwrite
bool
--overwrite
Allow existing batch export destinations
collision
enum: error, overwrite, suffix
error
--collision
Batch policy for existing destinations
theme
string
--theme
Select a named theme from config; --theme also finds installed themes
theme_file
string
--theme-file
Load styles from an upstream rich theme file ([styles] section); --theme and --theme-style override it
plugins
list of paths
--plugin
Load a runtime plugin: a WASM module (.wasm, sandboxed; the default wasm-plugins feature) or a native library (.so, .dylib, .dll, which runs its own code; a build with the dylib-plugins feature); repeatable. rich plugins list shows what is loaded
micro_project
bool
--micro-project
Load micro assets from the project's .rich/micro/ (off by default: a project's assets load only when you trust it; ./rich.toml cannot turn this on)
no_color
bool
NO_COLOR
--no-color
Disable colored output (as does a non-empty NO_COLOR)
sanitize
bool
--sanitize
Replace input terminal controls, JSON/notebook strings, titles and captions with visible inert text. On by default for content fetched from a URL, and for rich view, rich schema, rich log and text rich diff; --no-sanitize turns it off there
rich writes diagnostics to stderr and rendered output to stdout, so
rich --csv data.csv > table.txt keeps the two apart.
--report json writes the result/error envelope to stderr for the same reason:
stdout remains the rendered payload. rich doctor --report json is an
informational command: its diagnostic document is written to stdout instead.
Successful reports include ok, code, exit_code and a result object.
Failures include the same status fields plus message and an error object.
The top-level message is retained for simple shell consumers; structured
consumers can read error.message. Informational exits such as --help and
--version print their normal text and do not emit a report envelope.
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.