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.

capture_and_render.sh shares temporary setup, fixture lifecycle, PTY capture, rendering and media assembly across this recorder, image models and streaming text. Each recorder keeps its own scenes, rendering settings and assertions. Failures stop the recording; exit and interruption clean up its fixture and temporary state. Each run requires an empty output directory outside the repository so it cannot overwrite previous evidence.

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" /path/to/evidence/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" /path/to/evidence/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, file records and error responses.

List/get results

The list-get-results scenario compares the same two file records on the pager parent and the feature branch. Both commands use openai files list --max-items 2. The records have distinct IDs, filenames and sizes, with seven fields each so the complete before output fits in the 90-column by 24-row capture. The after scene retains ID, filename, purpose, bytes and status, followed by one Summary; use --format json for full data. notice after the list.

Two more scenes retrieve the first file before and after the change. The last scene uses openai --format json files retrieve file_training, demonstrating that the original object and created_at fields are still available. All five scenes use the same fixture server and expect exit 0. The recorder checks both file IDs in the list scenes, exactly one summary hint in each after scene, and the creation timestamp in the before and explicit JSON scenes.

Build the fixture as above, then capture the final feature binary using its actual full commit ID. For the September 2026 feature extraction, the pinned before commit is the pager cleanup parent ef4fd8b6baf818781ff5c5705f7e048e0efbe322. Build its binary independently, then supply both verified binary paths:

PATH="/Users/vguvvala/.cache/cli-terminal-replay/bin:$PATH" \
  bash scripts/demos/record.sh list-get-results \
  "$BEFORE_BINARY" "$AFTER_BINARY" \
  ef4fd8b6baf818781ff5c5705f7e048e0efbe322 \
  "$AFTER_SHA" \
  /absolute/path/to/list-get/media

Keep the media outside Git. Inspect before.png, after.png, before-retrieve.png, after-retrieve.png, explicit-json.png and frames from comparison.gif before using them for review. The fixture and recipe are synthetic; the screenshots and GIF must come from actual binary execution. list-get-results.tape preserves the same commands for a separate VHS capture.

Evidence and limits

The 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 recorded media outside the repository; executables may use ignored dist/. 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.