richterm

richterm#

ci docs pypi version Changelog Ruff License

richterm turns arbitrary terminal commands into Rich-rendered SVG transcripts. Use it from the command line or embed live terminal captures in Sphinx documentation.

Command-line quick start#

Run without installing anything permanently:

uvx richterm
$ uvx richterm --help usage: richterm [-?] [-V] [-h | --shown-command SHOWN_COMMAND] [-o OUTPUT]                 [--prompt PROMPT] [--theme THEME] ... Generate SVG transcripts of terminal commands rendered with Rich. positional arguments: command               Command to execute. Additional arguments are passed through                         verbatim. options: -?, --help            Show this help message and exit. -V, --version         show program's version number and exit -h, --hide-command    Do not include the command line in the generated transcript. -o, --outputOUTPUT   Write the SVG transcript to this path (defaults to a timestamped                         file in the current directory). --promptPROMPT       Prompt to display before the command. Accepts Rich markup. --themeTHEME         Terminal theme used for SVG export. Supported values: default,                         light, monokai, dimmed-monokai, night-owlish, svg-export.                         Defaults to $RICHTERM_THEME or 'default'. --shown-commandSHOWN_COMMAND                         Override the command text shown in the transcript without                         changing the executed command.

Key options:

  • --prompt: Rich markup shown before the command (defaults to $).

  • --theme: choose the Rich terminal export theme (default, light, monokai, dimmed-monokai, night-owlish, or svg-export).

  • --hide-command: omit the prompt/command from the SVG.

  • -o/--output: select the SVG destination; otherwise rich_term_<TIMESTAMP>.svg is created in the working directory.

  • --shown-command: render a different command string than the one executed (useful when the real invocation is noisy or repetitive).

Rich output is encouraged automatically: unless you opt out, the command runs with colour-friendly hints (TERM, FORCE_COLOR, CLICOLOR_FORCE, PY_COLORS, TTY_COMPATIBLE). Set RICHTERM_THEME to change the default export theme for both the CLI and Sphinx builds. Set RICHTERM_DISABLE_COLOR_HINT to 1 or export NO_COLOR to skip these tweaks. If your CI sets NO_COLOR but you still want colour, export FORCE_COLOR to 1.

To install the tool permanently:

uv tool install richterm

Sphinx directive#

Enable the extension in conf.py:

extensions = [
    "myst_parser",
    "sphinxcontrib.mermaid",
    "richterm.sphinxext",
]
richterm_prompt = "[bold]$"
richterm_hide_command = False
richterm_theme = "default"
# Optional default text to display instead of the executed command
richterm_shown_command = None

Use the directive inside MyST Markdown:

```{richterm} python -m rich --force-terminal rainbow
:theme: monokai
```

Or in reStructuredText:

.. richterm:: python -m rich --force-terminal rainbow
:theme: monokai
:shown-command: python -m rich rainbow

The directive executes the command during the build, embeds the SVG directly in HTML output, and falls back to a literal code block elsewhere. Override the prompt per block with :prompt:, choose a terminal palette with :theme:, hide the command with :hide-command:, or swap the displayed command while running another with :shown-command: (falls back to richterm_shown_command if set). If you hide the command, any :shown-command: value is ignored and a warning is emitted.

Same output, different themes#

The same ANSI-rich output can be rendered with different terminal themes:

$ python -m rich rainbow                                       Rich features                                           Colors   โœ“ 4-bit colorโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โœ“ 8-bit colorโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โœ“ Truecolor (16.7 million)โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โœ“ Dumb terminalsโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โœ“ Automatic color conversionโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„    Styles   All ansi styles: bold, dim, italic, underline, strikethrough, reverse, and   even blink.                                                                      Text    Word wrap text. Justify left, center, right or full.                         Lorem ipsum dolor Lorem ipsum dolor  Lorem ipsum dolorLoremipsumdolor sit amet,             sit amet,              sit amet,sitamet, consectetur          consectetur           consecteturconsectetur adipiscing elit.   adipiscing elit.   adipiscing elit.adipiscingelit. Quisque in metus   Quisque in metus   Quisque in metusQuisqueinmetus sed sapien            sed sapien            sed sapiensedsapien ultricies pretium ultricies pretium  ultricies pretiumultriciespretium a at justo.          a at justo.           a at justo.aatjusto. Maecenas luctus    Maecenas luctus     Maecenas luctusMaecenasluctus velit et auctor    velit et auctor     velit et auctorvelitetauctor maximus.               maximus.               maximus.maximus.    Asian    ๐Ÿ‡จ๐Ÿ‡ณ  ่ฏฅๅบ“ๆ”ฏๆŒไธญๆ–‡๏ผŒๆ—ฅๆ–‡ๅ’Œ้Ÿฉๆ–‡ๆ–‡ๆœฌ๏ผ                                             language  ๐Ÿ‡ฏ๐Ÿ‡ต  ใƒฉใ‚คใƒ–ใƒฉใƒชใฏไธญๅ›ฝ่ชžใ€ๆ—ฅๆœฌ่ชžใ€้Ÿ“ๅ›ฝ่ชžใฎใƒ†ใ‚ญใ‚นใƒˆใ‚’ใ‚ตใƒใƒผใƒˆใ—ใฆใ„ใพใ™           support   ๐Ÿ‡ฐ๐Ÿ‡ท  ์ด ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ๋Š” ์ค‘๊ตญ์–ด, ์ผ๋ณธ์–ด ๋ฐ ํ•œ๊ตญ์–ด ํ…์ŠคํŠธ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค                Markup   Rich supports a simple bbcode-like markup for color, style, and emoji! ๐Ÿ‘    ๐ŸŽ ๐Ÿœ ๐Ÿป ๐Ÿฅ– ๐ŸšŒ                                                                  Tables   DateTitleProduction BudgetBox Office โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€  Dec 20, 2019Star Wars: The Rise       $275,000,000  $375,126,118 of Skywalker          May 25, 2018Solo: A Star Wars         $275,000,000  $393,151,347 Story                 Dec 15, 2017Star Wars Ep. VIII:       $262,000,000$1,332,539,889 The Last Jedi         May 19, 1999Star Wars Ep. I: The      $115,000,000$1,027,044,677 phantom Menace    Syntax    1 defiter_last(values:Iterable[T{ highlighting 2 โ”‚   """Iterate and generate a tuโ”‚   'foo': [      &       3 โ”‚   iter_values=iter(values)โ”‚   โ”‚   3.1427,                          pretty    4 โ”‚   try:โ”‚   โ”‚   (   printing   5 โ”‚   โ”‚   previous_value=next(itโ”‚   โ”‚   โ”‚   'Paul Atreides',           6 โ”‚   exceptStopIteration:โ”‚   โ”‚   โ”‚   'Vladimir Harkonnen',      7 โ”‚   โ”‚   returnโ”‚   โ”‚   โ”‚   'Thufir Hawat'  8 โ”‚   forvalueiniter_values:โ”‚   โ”‚   )  9 โ”‚   โ”‚   yieldFalse,previous_vaโ”‚   ],                                10 โ”‚   โ”‚   previous_value=valueโ”‚   'atomic': (False, True, None) 11 โ”‚   yieldTrue,previous_value}   Markdown  # Markdown                             โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“                                         โ”ƒ             Markdown             โ”ƒ  Supports much of the *markdown*        โ”—โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”›  __syntax__!                                        Supports much of the markdown - Headerssyntax!                               - Basic formatting: **bold**,  *italic*, `code` โ€ข Headers                            - Block quotes โ€ข Basic formatting: bold, italic,    - Lists, and more...code  โ€ข Block quotes                        โ€ข Lists, and more...                    +more!   Progress bars, columns, styled logging handler, tracebacks, etc...           rendered in 42.4ms(cold cache) rendered in 18.0ms(warm cache) โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Help ensure Rich is maintained โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚Hope you enjoy using Rich!โ”‚ โ”‚โ”‚ โ”‚ Please consider sponsoring me if you get value from my work. โ”‚ โ”‚โ”‚ โ”‚ Even the price of a โ˜• can brighten my day!                  โ”‚ โ”‚โ”‚ โ”‚ https://github.com/sponsors/willmcgugan                      โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

Tutorials

How-to Guides

Reference

Explanation

Project Policies

Contents