Metadata-Version: 2.4
Name: richterm
Version: 0.1.0
Summary: Generate colorful screenshots of terminal commands
Keywords: 
Author: Martín Gaitán
Author-email: Martín Gaitán <gaitan@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: rich
Requires-Dist: sphinx>=7.4.7 ; extra == 'sphinx'
Requires-Dist: myst-parser>=3.0.0 ; extra == 'sphinx'
Requires-Python: >=3.10
Project-URL: Changelog, https://github.com/mgaitan/richterm/releases
Project-URL: Documentation, https://mgaitan.github.io/richterm
Project-URL: Funding, https://github.com/sponsors/mgaitan
Project-URL: Homepage, https://mgaitan.github.io/richterm
Project-URL: Issues, https://github.com/mgaitan/richterm/issues
Project-URL: Repository, https://github.com/mgaitan/richterm
Provides-Extra: sphinx
Description-Content-Type: text/markdown

# richterm

[![ci](https://github.com/mgaitan/richterm/workflows/ci/badge.svg)](https://github.com/mgaitan/richterm/actions?query=workflow%3Aci)
[![docs](https://img.shields.io/badge/docs-blue.svg?style=flat)](https://mgaitan.github.io/richterm/)
[![pypi version](https://img.shields.io/pypi/v/richterm.svg)](https://pypi.org/project/richterm/)
[![Changelog](https://img.shields.io/github/v/release/mgaitan/richterm?include_prereleases&label=changelog)](https://github.com/mgaitan/richterm/releases)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/mgaitan/richterm/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/mgaitan/richterm/blob/main/LICENSE)

`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:

```bash
uvx richterm -- python -m rich
```

Install globally when you are ready:

```bash
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:

```bash
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:

```bash
uv add richterm[sphinx]
```

```python
# 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:

````md
```{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:

```bash
uv run --extra sphinx pytest
```

Build the documentation (which exercises the directive itself):

```bash
make docs
```
