| name | recording-cli-gifs |
| description | Use when creating, editing, validating, rendering, or debugging local CLI and TUI demo GIFs with asciinema+agg or VHS, including recorder selection, scripted terminal recordings, `.tape` files, Hide/Show sections, waits, sleeps, and reproducible demo artifacts.
|
Recording CLI GIFs
Treat a demo GIF as a glanceable loop,
not as a narrated lesson or proof that a command can run.
Reason across four boundaries:
what the viewer knows and should notice,
what stays stable and visibly changes,
who drives each action after capture begins,
and what evidence supports the recording's claims.
Keep recordings local.
Do not publish recordings to hosted services.
Model the viewer
Set an internal brief with the audience, one takeaway, and the boundary.
Use the brief to remove material,
not as content for the GIF.
Show one command, interaction, transition, or before-and-after result.
If that requires several definitions, examples, exceptions, or an argument,
narrow the takeaway or use documentation or video.
Assume little reading time.
Let the real terminal state and motion carry the meaning.
Use a short cue only when the visible states cannot show where to look.
Skip title cards, glossaries, and prose recaps by default.
If the viewer only needs to notice that an unfamiliar field changed,
show the change without defining or interpreting the field.
When meaning is essential,
verify it and narrow the GIF until it can be shown briefly.
Design the visible argument
Use one small example and the shortest visible sequence that proves the takeaway:
- Start at the useful initial state.
- Show the representative command or interaction.
- Change one relevant thing while keeping identity and context stable.
- Hold the result long enough to inspect.
- Return to the opening state without implying a false reverse transition.
Hide setup, cleanup, and unrelated output unless they are the subject.
Keep visible commands representative of real use,
with recording-only environment configuration at the recorder boundary.
Preserve identity through stable position, naming, color, and notation.
Reserve motion for the relevant change,
and let the final visible state embody the takeaway.
