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] [-o OUTPUT] [--prompt PROMPT]                 [--shown-command SHOWN_COMMAND] ... 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. --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 $).

  • --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_DISABLE_COLOR_HINT=1 or export NO_COLOR to skip these tweaks. If your CI sets NO_COLOR but you still want colour, export FORCE_COLOR=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
# 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
```

Or in reStructuredText:

.. richterm:: python -m rich --force-terminal rainbow
: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:, 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 (a warning is emitted).

Documentation

Contents