demos

CLI comparison recordings

record.sh runs real before/after binaries against the fixed synthetic API in main.go. Commands run as openai on a PTY with a fake key and an isolated environment. No live OpenAI requests or uploads are made.

The tested replay tools are asciinema 3.2.1, agg 1.9.0 and ffmpeg 4.4.8. Install these tools independently and put asciinema, agg, ffmpeg and ffprobe on PATH. This is a terminal replay, not a native Apple Terminal, PowerShell or cmd.exe capture. The retained .tape recipe is for VHS; it does not produce the asciinema/agg media generated by this runner.

Reproduce

Run from the repository root. Build the fixture into the ignored output folder:

mkdir -p dist/demos/bin
go build -o dist/demos/bin/demo-api ./scripts/demos/main.go

Independently build a before CLI from the comparison base and an after CLI from the proposed commit. Verify that each binary comes from its supplied commit; the recorder logs commit IDs and file hashes but cannot establish provenance. Then run:

bash scripts/demos/record.sh readable-output \
  /path/to/before/openai /path/to/after/openai \
  "$BEFORE_SHA" "$AFTER_SHA" dist/demos/readable-output

Both SHA arguments must be full 40-character commit IDs. Readable output uses main as its comparison base. For helpful errors, use the readable-output parent as the before commit and run:

bash scripts/demos/record.sh helpful-errors \
  /path/to/before/openai /path/to/after/openai \
  "$BEFORE_SHA" "$AFTER_SHA" dist/demos/helpful-errors

Use DEMO_API_BINARY to select another prebuilt fixture.

The runner checks actual exit status and expected fixture text for each scene. Readable scenes expect exit 0; helpful-error scenes expect exit 1. The local fixture and temporary state are cleaned up on exit. The fixture binds only to loopback and serves fixed model data and error responses.

Evidence and limits

The three scenes show before, after and explicit JSON output. Each uses bash, 90 columns by 24 rows, Menlo at 22 px, Dracula colors and a 3.5-second final pause. If Menlo is unavailable, supply it locally before recording so styling matches. Terminal color detection can add a delay; recorded output and timing are not rewritten.

Each original scene is rendered separately with agg, then ffmpeg joins the full GIF frames while retaining the recorded timing and final pauses (within GIF timing precision). This avoids partial glyphs that agg 1.9.0 can retain across screen clears in a merged recording. The combined cast is preserved alongside the individual captures for provenance.

The output folder contains comparison.gif, before.png, after.png, explicit-json.png, individual scene GIFs and their comparison-scenes.txt list, individual and combined .cast files, text transcripts, and the retained VHS tape. metadata.txt and media.json record commits, hashes, actual exit codes, OS, shell, tool versions, dimensions and duration.

Inspect the GIF and screenshots for readable text, clipping, timing, correct behavior and sensitive data before sharing. Keep all media and executables in ignored dist/ or outside the repository. Regenerate evidence after changes that affect the demonstrated behavior. Retain only the runner, fixture and recipes in Git.

For a separate VHS capture, provide DEMO_BEFORE_DIR and DEMO_AFTER_DIR containing the matching binaries named openai, plus OPENAI_BASE_URL pointing to this local fixture and a synthetic OPENAI_API_KEY. Run the tape from an ignored output directory with vhs and validate it first with vhs validate. Do not label asciinema/agg output as a VHS or native-terminal capture.

Official documentation: asciinema recording, configuration, agg rendering, VHS, and ffmpeg.