record-asciinema

Record CLI Demo (asciinema)

Record a terminal demonstration with asciinema, render the .cast to a GIF (or SVG fallback) so it can be embedded inline in a GitHub PR or comment, and return the path to the rendered asset.

This is the recording primitive for CLI changes. For web UI changes, use /record-playwright.

Recording principle: show commands

Always display the commands being run in the recording so viewers can see what was executed and reproduce it. Hide commands only when it is appropriate for the purpose of the demo (e.g. focusing purely on output, or a polished marketing-style demo where the command is irrelevant). When in doubt, show the command.

Prerequisites

• asciinema installed
• One of agg, asciicast2gif, or svg-term-cli (which provides the svg-term binary) installed (for rendering). agg is preferred (fastest, best quality).
• If none are installed, the skill still returns the raw .cast with playback instructions.

Inputs

The skill is driven by the following inputs. Set them from context, or accept them from the command line.

Input	Meaning	Default
$RECORD_SLUG ($1)	Filename slug for the recording, e.g. verbose-flag	demo
$RECORD_TITLE	Human-readable title shown in the asciinema player	CLI demo
$RECORD_DIR	Output directory for .cast / .gif	/tmp/record-asciinema
$RECORD_COMMAND ($2..)	A single command to record non-interactively (single-shot demos)	(none; interactive mode)

If $RECORD_COMMAND is provided, the demo runs that one command and exits. If not, the skill drops into an interactive asciinema shell where the agent types the relevant commands and exits.

Workflow

Inputs resolved (slug, title, dir, command?)
          |
          v
asciinema available?
   /            \
 Yes             No
  |               |
  v               v
Record .cast   Return nothing,
               caller falls back to text
  |
  v
Render to GIF (agg -> asciicast2gif -> svg-term)
   |
   v
Return rendered asset path (+ raw .cast)