rich-cli: render Markdown, JSON and CSV in the terminal with the rich command

What rich-cli does that cat, less and bat do not

The tool installs a command called rich. You give it a path or a URL, and it decides what kind of content it is looking at, then renders it with colors, styles and structure instead of raw bytes. The README lists dedicated handling for Markdown, JSON, CSV and TSV, Jupyter notebooks, and general source files, where the format is inferred from the filename and the lexer can be overridden with --lexer or -x.

The audience is narrow and practical: developers who live in a terminal and want to read a README, inspect a JSON payload, or skim a CSV without opening an editor. It is also useful when something is being piped. The README states that where rich accepts a path you can pass - to read from stdin, which makes it a formatting stage in a shell pipeline rather than only a file viewer.

It is not a general purpose pager like less, and it is not the Rich library. The distinction matters. Rich is a Python package you import; rich-cli is a command that uses it. If your goal is to print styled tables from inside your own program, the CLI is the wrong entry point.

How rich-cli decides what to render

The repository layout shows a single source tree under src/ and a test suite under tests/, with the console entry point declared in pyproject.toml as rich = "rich_cli.__main__:run". So there is one command, and the behavior is selected by switches and by the detected file type.

The detection rule stated in the README is filename based. A file ending in .md is treated as Markdown, .ipynb as a Jupyter notebook, .json as JSON, and .csv or .tsv as a table. When detection is wrong or absent, you override it: --markdown or -m for Markdown, --json or -J for JSON, --ipynb for notebooks, and --lexer or -x for the syntax highlighting lexer.

The notebook case is the clearest example of how the design composes. According to the README, all options that apply to syntax highlighting can be applied to code cells, and all options that apply to Markdown can be applied to Markdown cells. One command, two rendering paths, chosen per cell.

Several options are global rather than format specific, which is why the tool stays small. Style (--style or -s), alignment (--left, --center, --right, or -l, -c, -r), width (--width or -w) and the pager (--pager) apply on top of whatever is being rendered. That layering is the whole architecture as far as the repository reveals it: detect or accept a format, render it through Rich, then apply presentation options to the result.

Installing rich-cli and rendering a first file

The README gives four install routes. On Windows and Linux it recommends pipx, which puts the command in its own environment. On macOS it points at Homebrew, where the formula is named rich rather than rich-cli. As a universal option it can be installed as a Python package with pip, or with conda or mamba from conda-forge.

pipx install rich-cli

After installation the README says you should have the rich command in your path. Confirm that and read the available switches:

rich --help

The first real use is highlighting a source file. Passing a path is enough; the lexer is inferred from the filename.

rich loop.py

Line numbers and indentation guides are two switches that change readability more than they change output size:

rich loop.py -n -g

For Markdown the README notes that a .md file is auto-detected, so the explicit flag is optional:

rich README.md

If your terminal supports hyperlinks, --hyperlinks or -y renders links as clickable text instead of printing full URLs, which is the difference between a readable paragraph and a wall of addresses. To write the same rendering to a file instead of the terminal, add --export-html or -o with an output path; the README states that this works with any command and that the file appears in the current working directory.

rich README.md -o readme.html

Theming, wrapping and the pager are where the friction is

Syntax highlighting accepts a Pygments theme through --theme, and the default can be set with the RICH_THEME environment variable. The README gives dracula as its example and states that the environment variable form is equivalent to passing the flag.

RICH_THEME=dracula rich loop.py

Wrapping is the option most likely to surprise you. By default rich wraps lines that do not fit the available width, and --no-wrap disables that. The README also documents a separate --soft option that switches from word wrapping, which inserts newlines, to soft wrapping. Two wrapping controls with overlapping names is a small design wart, and the README does not explain how they interact when both are relevant.

The built in pager is the second rough edge. --pager displays content in a pager application you scroll with cursor keys, page up and down, home and end, the scrollbar, or vi navigation (j, k, ctrl-d, ctrl-u). That is a real feature, but it is not less: there is no documented search, no filter, and no configuration file. If your reading workflow depends on searching inside a file, the pager will not carry it.

One behavior deserves attention before you build a pipeline around it. The README states that when rich is not writing directly to the terminal it disables ANSI color codes, and that --force-terminal or -F tells it to keep them. So piping rich output into another program silently drops the styling unless you pass the flag. That is a sensible default for redirected files, and a confusing one the first time colored output disappears.

Reading from stdin and from URLs

Two input paths go beyond local files, and both are documented in the README with examples.

For stdin, pass - where a path would go. The README's example pipes a Markdown file through rich and adds --force-terminal so the ANSI codes survive the pipe:

cat README.md | rich - --markdown --force-terminal

For network input, a URL starting with http:// or https:// is read directly. The README's example fetches a Markdown file from GitHub raw and renders it:

rich https://raw.githubusercontent.com/Textualize/rich-cli/main/README.md --markdown

This is convenient and also the part of the tool with the least visible machinery. The dependency list in pyproject.toml includes requests (>=2.0.0,<3.0.0), which is consistent with URL fetching, but the README documents no timeout, no redirect policy, no caching and no authentication. For a public README over HTTPS that is fine. For an internal endpoint behind auth, the documented surface stops short.

rich-cli versus the Rich library, and versus bat

The most common confusion is between rich-cli and Rich. They share a name and a maintainer, and they solve different problems. Rich is the Python library you import to build styled console output, tables and progress bars inside your own program. rich-cli is a command that renders existing files. If you want Rich's printing behavior from Python, the README's own printing section shows the CLI equivalent, which is not the same thing as the library API:

rich "Hello, [bold magenta]World[/]!" --print

That --print or -p mode treats the first argument as console markup, and --style applies a style to the output, for example "on blue". It is a way to get styled text out of a shell script. It is not a substitute for importing Rich when you need layout, live updates or progress rendering.

The closer comparison in day to day use is bat, a syntax highlighting cat replacement. The difference in approach is scope. bat centers on highlighting files with line numbers and git integration, and delegates paging to less. rich-cli centers on rendering structured formats: Markdown with terminal hyperlinks, JSON pretty printing, CSV and TSV as tables, Jupyter notebooks cell by cell, plus HTML export. If your need is highlighting source code, both work and bat's pager integration is more conventional. If your need is reading a Markdown document or a notebook in the terminal, rich-cli covers ground bat does not.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-12. The most recent release listed is v1.8.1 on 2025-07-04, described as fixing warning messages; before that, v1.8.0 dates to 2022-05-07 and v1.7.0 to 2022-05-01. That release history is worth reading carefully: the feature work is old, and the recent activity is a patch release. The pyproject.toml still carries black 22.3.0 and mypy 0.942 in its dev dependency groups, which is consistent with a codebase that is maintained rather than actively developed.

The licence is MIT, declared in pyproject.toml as license = "MIT" with license-files = ["LICENSE"], and a LICENSE file sits at the top level. MIT is permissive, so redistributing or bundling the tool is straightforward. That is a statement about the licence text, not legal advice, and anyone embedding it in a product should read the LICENSE file themselves.

The upgrade cost is dominated by one line in pyproject.toml: rich-cli 1.8.1 depends on rich >=12.4.0,<13.0.0. The upper bound is a hard pin to the 12.x line. If you already have a newer Rich installed in the same environment, pip will either install a second copy or refuse, depending on how you invoked it, which is one reason the README leads with pipx for Windows and Linux. Python support is declared as >=3.9 with classifiers through 3.13. The other pinned dependencies are click >=8.0.0,<9.0.0, requests >=2.0.0,<3.0.0, textual >=0.1.18,<0.2.0 and rich-rst >=1.1.7,<2.0.0.

Frequently asked questions about rich-cli

The README answers most first questions directly, so the entries below stick to what it documents and skip what it does not.

What is rich-cli? It is a command line toolbox for fancy output in the terminal, built with Rich, that installs a command named rich. It highlights many file types and has specialized rendering for Markdown and JSON, and it can also markup and format text from the command line.

How do I install rich-cli? On Windows and Linux the README recommends pipx install rich-cli. On macOS it points at Homebrew with brew install rich, and as a universal option it can be installed with python -m pip install rich-cli or with mamba install -c conda-forge rich-cli.

Does rich-cli read from stdin? Yes. Where rich accepts a path you can enter -, and the README notes that ANSI color codes are disabled when output is not going directly to a terminal, so --force-terminal or -F is needed to keep them.

Can rich-cli export to HTML? Yes. Adding --export-html or -o with an output path writes an HTML file, and the README states this works with any command.

The README does not document a configuration file, a search function in the pager, or a way to authenticate when fetching a URL, so those questions are left unanswered here rather than guessed at.

Editorial conclusion

Adopt rich-cli if you read Markdown, JSON, CSV or source files in a terminal and want one command that handles all of them, with HTML export and stdin support. Do not adopt it if you need a scripting API for terminal output in your own program, since that is what the Rich library itself is for, or if you need a general purpose pager. Before installing, verify that your Python is 3.9 or newer and check the pinned rich dependency range, because rich-cli 1.8.1 declares rich >=12.4.0,<13.0.0, and a preinstalled newer Rich will not satisfy it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Textualize/rich-cli on GitHub