The macOS install line installs a different package
Rich-cli is a command line toolbox for fancy output in the terminal
At a glance
- What is it?
- rich-cli puts Rich behind a single rich command that highlights files, renders Markdown, notebooks, JSON and CSV, and prints console markup. Its README gives three install paths, one of which names a different package, and one short flag that means two different things.
- Who is it for?
- rich-cli is worth installing for reading source, diffs and Markdown in a terminal without leaving the shell, and its flag set is broad enough that the pager, the export and the stdin paths will get used. Four things to check first.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Textualize/rich-cli3,779 ★ · +53
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| Textualize/rich-cli | 3.7k | 3.8k |
53 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The macOS install line names a different distribution
Three install paths are offered and two of them install the package this repository builds. On Windows and Linux it is pipx:
pipx install rich-cliThe universal section gives either of two:
python -m pip install rich-climamba install -c conda-forge rich-cliThe macOS section is the odd one out. It says you can install Rich-CLI with Homebrew, and the command is:
brew install richThat installs a formula named rich, not rich-cli. So the platform the project organises its own instructions around is the one where the documented command does not install the tool in this repository. Whether the formula is a wrapper that depends on the CLI is not something the README says, and a user on a Mac following the page literally ends up with a command that may come from the other package.
-F is documented twice with two different meanings
One short option carries two definitions in the same file. The stdin section says that when rich is not writing directly to the terminal it disables ansi colour codes, and that you may want to add --force-terminal or -F to keep them:
cat README.md | rich - --markdown --force-terminalThe text justification section, further down, lists the single letter equivalents of --text-left, --text-right, --text-center and --text-full as -L, -R, -C and -F. So -F is both force terminal and text full in the same document, and neither mention flags the collision. The same pattern appears with the alignment options, which take -l, -c and -r, meaning -c is center for the block while -C is center for the text inside it. Short flags here follow the case for that distinction, which makes the -F reuse the exception worth knowing about before you script around it.
The console script is called rich and rich is a dependency
The packaging metadata registers one command:
[project.scripts]
rich = "rich_cli.__main__:run"The name is not namespaced, and the same file lists the library it wraps as a dependency, rich (>=12.4.0,<13.0.0). So the distribution is rich-cli and the command it puts on your path is the short one, which is also the name of the upstream library and, as the Homebrew line shows, the name of another distribution's formula. That is a deliberate choice for a companion tool rather than an oversight, since it is what makes the documented examples read as `rich loop.py`, but it does mean the name on your path does not tell you which package installed it. There is a second entry point as well, under [project.entry-points."pipx.run"], mapping rich-cli to the same function, which is what lets pipx fetch and run the tool without installing it first.
rich will fetch a URL when given one
The tool is not only a file reader. A section states that the rich command can read files from the internet given a URL starting with http:// or https://, and the example points at a raw README on GitHub:
rich https://raw.githubusercontent.com/Textualize/rich-cli/main/README.md --markdownCombined with the pipx.run entry point, that makes two network paths into the same binary: an explicit URL argument, and pipx resolving and downloading the package on a first run. Neither is a problem on its own, but both mean the tool does more than the file it was pointed at, and a script that pipes a URL into rich should assume the response is rendered as markup. The related stdin path is the quiet one: wherever a path is accepted you can pass - to read from standard input, which is the form you want in a pipeline.
Every format has both a flag and an auto-detect rule
Five file types are recognised by extension, and every one of them also has a switch. A file ending in .md is detected as Markdown, .ipynb as a Jupyter notebook, .json gets JSON pretty formatting and highlighting, and .csv or .tsv is displayed as a table. The flags are --markdown with -m, --ipynb with no short form given, --json with -J, and the CSV path has no flag of its own because detection is the whole story there. Notebooks get one extra rule: every option that applies to syntax highlighting applies to code cells, and every option that applies to Markdown applies to Markdown cells, so one command renders a mixed document. Syntax highlighting itself is inferred from the filename too, with --lexer or -x to override the guess, and the sentence that explains it has a typo, saying rich will deduce the format of the via from the filename. Line numbers come from --line-number or -n, indentation guides from --guides or -g, and a theme from --theme or from the RICH_THEME environment variable, which the file gives as an exact equivalent of passing the flag. Hyperlinks are opt-in as well, with --hyperlinks or -y emitting links instead of full URLs, and only on terminals that support them.
Exporting covers HTML while two releases are titled around SVG
The exporting section is short and names one output format. In addition to rendering to the console, rich can write an HTML file, with --export-html or -o followed by the path:
rich README.md -o readme.htmlThat is the whole section, and the file then says you should find readme.html in the current working directory. The release history tells a different story about output formats. Of the three most recent releases, v1.8.0 is titled Improved SVG export and v1.7.0 is titled New Jupyter Notebook support and SVG export, while only the newest, v1.8.1, is titled Fixed warning messages. So SVG export was the headline twice and the section documenting exports mentions only HTML. Either the SVG path moved elsewhere in the documentation or the capability is no longer reachable from the command the README teaches.
--left aligns the block, --text-left aligns the text inside it
There are two families of alignment options and the README spends a paragraph separating them, because the difference is invisible without a width. The --left, --center and --right options, with -l, -c and -r, position the block of text within the terminal dimensions. The --text-left, --text-center, --text-right and --text-full options, with -L, -R, -C and -F, define how the text is rendered within that block. The examples pin the block at 40 characters with -w 40, centre it with -c, and then vary the text justification inside it. The same width option carries a related behaviour: by default rich wraps lines that do not fit, and --no-wrap turns that off, with --soft available when you want soft wrapping instead of inserted newlines. A third family sits alongside both, since --style or -s applies one style to the whole output, with the syntax documented separately from the markup.
Dev tooling is pinned to 2022 and the metadata declares itself twice
The project manifest describes itself two ways and pins its tools to a specific vintage. Both a PEP 621 project table and a Poetry section are present, the latter carrying a comment that python = ">=3.9,<4.0" is required for locking in Poetry 2, and the build requirement asks for poetry-core >=2.0.0,<3.0.0 while a poetry.lock from the previous generation sits in the tree. Dev dependencies appear twice, once as a Poetry group and once as a dependency group, both naming black 22.3.0 and mypy 0.942, versions from 2022. That vintage matches the release history: two releases in early May 2022, then v1.8.1 in July 2025 with the title Fixed warning messages, and a last push to main dated 2026-08-12 with no tag attached. The dependency ranges are the other thing to check, with textual bounded to >=0.1.18,<0.2.0, a pre-1.0 range that will not follow that library forward.
Editorial conclusion
rich-cli is worth installing for reading source, diffs and Markdown in a terminal without leaving the shell, and its flag set is broad enough that the pager, the export and the stdin paths will get used. Four things to check first. Which install path you use, because the macOS line installs a different distribution than the other two. Whether you rely on short flags, since -F is documented twice with two meanings. Whether your output is going to a pipe, where colour codes are dropped unless you pass --force-terminal. And whether the pinned dependency ranges still resolve for you, since textual is bounded below 0.2.0.
Frequently asked questions
What is rich-cli?
A command line toolbox for fancy output in the terminal, built with Rich. The rich command syntax highlights many file types with specialized rendering for Markdown and JSON, renders notebooks and CSV tables, and can print console markup.
How do you install rich-cli?
With `pipx install rich-cli` on Windows and Linux, or `python -m pip install rich-cli` or `mamba install -c conda-forge rich-cli` as the universal options. The macOS section instead gives `brew install rich`, which names a different distribution.
What does the --print option do in rich-cli?
It makes rich treat the first argument as console markup, similar in design to bbcode, so styles can be inserted inline, for example rich "Hello, [bold magenta]World[/]!" --print. Styles can also be applied to the whole output with --style.
Does rich-cli keep colours when its output is piped?
No, not by default. When rich is not writing directly to the terminal it disables ansi colour codes, so the README suggests --force-terminal or -F, as in cat README.md | rich - --markdown --force-terminal. Elsewhere in the same file -F is listed as the short form of --text-full.
Which Python versions and dependencies does rich-cli require?
requires-python is >=3.9, and classifiers list Python 3.9 through 3.13. Dependencies are bounded: rich >=12.4.0,<13.0.0, 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.
What does the --pager option do in rich-cli?
It displays the content with a built in pager application. The README says to scroll with the cursor keys, page up and page down, home and end, the scrollbar at the right of the terminal, or vi navigation with j, k, ctrl-d and ctrl-u.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/textualize-rich-cli)Star history chart for your README
[](https://hysenlabs.com/projects/textualize-rich-cli)Was this useful?