richterm 0.1.0

Generate colorful screenshots of terminal commands

richterm

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

Quick start

Run the CLI without installing anything permanently:

uvx richterm -- python -m rich

Install globally when you are ready:

uv tool install richterm
richterm --prompt "[bold green]❯" python -c "print('hello')"

Each invocation writes an SVG named rich_term_<TIMESTAMP>.svg (or the file passed with -o/--output) and echoes the command output back to the terminal.

To keep colours vibrant even in non-interactive captures, richterm sets friendly defaults: TERM=xterm-256color (when missing) plus FORCE_COLOR=1, CLICOLOR_FORCE=1, PY_COLORS=1, and TTY_COMPATIBLE=1 unless you override them. Opt out with RICHTERM_DISABLE_COLOR_HINT=1 or by exporting NO_COLOR.

Command-line usage

usage: richterm [-h|--hide-command] [-o PATH] [--prompt STR] <command...>

• --hide-command hides the prompt and command line in the transcript.
• --prompt accepts Rich markup and defaults to $.
• -o/--output selects the SVG path; otherwise a timestamped filename is generated.

Examples:

richterm ls -la
richterm --prompt "[bold blue]λ" -o docs/_static/listing.svg git status --short
richterm --hide-command python -c "print('\033[31merror\033[0m')"

Sphinx integration

Install the optional Sphinx extras and enable the extension:

uv add richterm[sphinx]

# docs/conf.py
extensions = [
    "myst_parser",
    "sphinxcontrib.mermaid",
    "richterm.sphinxext",
]
richterm_prompt = "[bold]$"
richterm_hide_command = False

Then use the directive in MyST or reStructuredText:

```{richterm} python -m rich --force-terminal --no-color-system example
```

The directive executes the command during the build, embeds the SVG directly in HTML output, and falls back to a literal block for non-HTML builders. The :prompt: and :hide-command: options mirror the CLI flags.

Development

Tests depend on the Sphinx extras:

uv run --extra sphinx pytest

Build the documentation (which exercises the directive itself):

make docs