termstage

Generate polished terminal demo SVGs from a YAML file. No recording, no live shell, no asciinema.

Write what you want the terminal to show. Get a clean SVG you can drop into any README, doc, or portfolio.

Install

As a standalone tool (recommended):

pipx install termstage
# or
uv tool install termstage

Into a project:

uv add termstage
# or
pip install termstage

The Flow

1. Scaffold a starter file

termstage init

Creates demo.yaml in the current directory with example steps you can edit.

2. Edit demo.yaml

Open demo.yaml and replace the example steps with your own commands and output. See YAML format below.

3. Preview in browser

termstage preview demo.yaml

Opens a rendered SVG in your default browser. Iterate here until it looks right.

4. Render to SVG

# Static SVG
termstage render demo.yaml

# Animated CSS typewriter (recommended for READMEs)
termstage render demo.yaml --animated

# Custom output path
termstage render demo.yaml --animated -o assets/demo.svg

5. Embed in your README

![demo](demo.svg)

Or for more control over sizing:

<img src="demo-animated.svg" alt="demo" width="700">

The animated SVG uses pure CSS — no JavaScript. Works on GitHub, GitLab, and anywhere SVG is rendered.

YAML Format

title: "my-cli"        # Title bar text
theme: dark            # dark | light | dracula | nord  (default: dark)
prompt: "$ "           # Prompt string (default: "$ ")
width: 700             # SVG width in pixels (default: 700)

steps:
  - cmd: "my-cli --version"
    output: "my-cli 1.0.0"

  - cmd: "my-cli process data.csv"
    output: |
      Reading data.csv...
      Processed 10,000 rows
      Output → results.jsonl

  - comment: "# Comments render without a prompt, styled as code comments"

  - cmd: "my-cli --help"
    output: |
      Usage: my-cli [OPTIONS] COMMAND

        process   Process a CSV file
        export    Export results

      Options:
        --help    Show this message and exit.

Step types

Top-level fields

Themes

termstage themes

Set with theme: <name> in your YAML.

Commands

License

MIT