richterm

CI docs pypi version Changelog Ruff License

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

This project was created and is still maintained with python-package-copier-template.

Quick start

Run the CLI without installing anything permanently:

uvx richterm

To install the tool permanently:

uv tool install richterm

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; if your CI sets NO_COLOR but you still want colour, explicitly set FORCE_COLOR=1.

Command-line usage

usage: richterm [-h|--hide-command] [-o PATH] [--prompt STR] [--shown-command 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.
  • --shown-command lets you display a different command than the one executed (handy when a fixture command would distract readers). Cannot be combined with --hide-command.

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')"
richterm --shown-command "pytest -q" python -c "print('actually running something else')"

Sphinx integration

richterm optionally works as a Sphinx extension. Install the extras and enable it in your conf.py:

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:

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

Or in 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

Or directly make test

Build the documentation, which exercises the directive itself:

make docs

Project links

Data verified by PyPI on Jul 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tin_nqn from gravatar.com tin_nqn

Credits

Author: Martín Gaitán

GitHub Statistics

Data verified by PyPI on Jul 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.11

Provides Extra

sphinx

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

richterm-0.3.0.tar.gz (9.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

richterm-0.3.0-py3-none-any.whl (10.5 kB view details)

Uploaded Python 3

File details

Details for the file richterm-0.3.0.tar.gz.

File metadata

  • Download URL: richterm-0.3.0.tar.gz
  • Upload date:
  • Size: 9.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for richterm-0.3.0.tar.gz
Algorithm Hash digest
SHA256 1b400a5773952135522140418bcdfdb8dc2bd4779c09987fcdde9baf74bec066
MD5 eac8e046b84d3fccedf1c9873cd894b6
BLAKE2b-256 4549ae8766d5fdedaf1c8f0beed251490c4d3449bc5be0a2955fa5744b845ff7

See more details on using hashes here.

Provenance

The following attestation bundles were made for richterm-0.3.0.tar.gz:

Publisher: cd.yml on mgaitan/richterm

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file richterm-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: richterm-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 10.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for richterm-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7819145cc67a7a03a61eb23db89cb7e0d029a379a731f8b58e087ffebb1ef001
MD5 2c9de281895269a8bcd7e1dc34d3d2c3
BLAKE2b-256 833d3acec66248fee8292f26d1cba18fb3be171acfe23bf19d368c902184a30f

See more details on using hashes here.

Provenance

The following attestation bundles were made for richterm-0.3.0-py3-none-any.whl:

Publisher: cd.yml on mgaitan/richterm

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page