Recording and replay
Save a session to an asciicast file and play it back.
porthole host --recordPorthole writes the session to an asciicast file and tells you where:
⏺ Recording to porthole-20260813-142207.castWhen the session ends:
⏺ Recording saved: porthole-20260813-142207.cast (1284 events)
Play it with: porthole replay porthole-20260813-142207.castChoose the path yourself with --record-output, and give the recording a title
that is stored in the file header with --title (which implies --record):
porthole host --record-output demo.cast --title "Deploy walkthrough"Both have environment equivalents — PORTHOLE_RECORD_OUTPUT and
PORTHOLE_TITLE — which is the convenient form inside a wrapper script.
What gets recorded
The bytes the viewer receives. That has one consequence worth knowing: with
--mask, the recording is masked too, because
redaction happens before the stream is tapped. A recording of a masked session
is safe to share on the same terms the session was.
If output outpaces the recorder, events are dropped rather than blocking your shell, and the summary says how many. A recording is not worth stalling a terminal for.
Playing it back
porthole replay demo.cast| Flag | Default | Description |
|---|---|---|
--speed <n> | 1 | Playback speed multiplier, e.g. 2 for double speed. |
--idle-limit <duration> | 2s | Cap on any single pause. 0 replays real timings. |
--from <duration> | 0 | Skip ahead, replaying earlier output instantly. |
--info | false | Print recording metadata and exit. |
--idle-limit defaults to 2 seconds because real sessions contain long pauses
where someone was reading or thinking, and replaying those faithfully makes a
five-minute recording take five minutes of nothing happening.
porthole replay demo.cast --speed 2 --from 1m30sPlayback is forward-only. Recorded output is raw ANSI written straight to your terminal — the terminal is the renderer. Seeking backwards would mean reconstructing screen state at an arbitrary point, which needs a full emulator; use a web player if you need that.
The format
asciicast v2, not v3.
v3 is the newer spec and the asciinema CLI's default since 3.0, but v2 is read
by every player and converter in circulation — current asciinema, agg,
asciinema-player — while v3 readers are limited to first-party tooling
refreshed since late 2025. A recording is only useful if it plays somewhere.
So your files work with the wider ecosystem, not just with Porthole:
asciinema play demo.cast
agg demo.cast demo.gifA recording whose process was killed mid-write is still readable up to the last complete event.
Recording from the viewer's side
A viewer can record what they are shown:
porthole join p3rx-9kma --record watched.castThe host is not notified that a viewer is recording. Whether that is fine depends entirely on the relationship, and it is a thing to agree on before the session rather than discover after it.