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 warning:Malware checks are experimental and may change without warning. Pass  `--preview-features malware-check` to disable this warning. 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 warning:Malware checks are experimental and may change without warning. Pass  `--preview-features malware-check` to disable this warning.                                       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  # MarkdownMarkdown Supports much of the *markdown*        Supports much of the markdown __syntax__!syntax!                               - Headers • Headers                            - Basic formatting: **bold**,  • Basic formatting: bold, italic,    *italic*, `code`code - Block quotes • Block quotes                       - Lists, and more... • Lists, and more...                    +more!   Progress bars, columns, styled logging handler, tracebacks, etc...           rendered in 46.0ms(cold cache) rendered in 16.4ms(warm cache) ╭──────────────────────────── Help ensure Rich is maintained ────────────────────────────╮ ││ │Hope you enjoy using Rich!│ ││ │  Consider sponsoring to ensure this project is maintained.                             │ ││ │https://github.com/sponsors/willmcgugan│ ││ ╰────────────────────────────────────────────────────────────────────────────────────────╯

Tutorials

How-to Guides

Reference

Explanation

Project Policies