ttylog

Record your terminal. Trim the dead air. Share as a single HTML file. No account. No upload.

ttylog (TeleTYpewriter log) records your terminal session to a standard .cast file (asciinema v2 format), lets you trim out the idle gaps, replay it in your terminal, and export it as a fully self-contained HTML file you can open in any browser — no server, no asciinema account, no upload required.

The exported HTML embeds the player and the recording in a single file. Send it in a Slack message, attach it to a GitHub issue, drop it in docs. It just works.

Install

pip install ttylog

Or with pipx:

pipx install ttylog

Note: Recording (ttylog record) requires Linux or macOS — it uses Unix PTY. Playback, trimming, and HTML export work on all platforms including Windows.

Usage

Record

# Record your default shell
ttylog record session.cast

# Record a specific command
ttylog record session.cast --command "python demo.py"

# Add a title
ttylog record session.cast --title "Deploy walkthrough"

# Suppress the startup banner
ttylog record session.cast --quiet

Press Ctrl-D or type exit to stop recording.

Replay

# Replay at normal speed
ttylog play session.cast

# Replay at 2× speed
ttylog play session.cast --speed 2

# Replay at 0.5× (slow motion)
ttylog play session.cast --speed 0.5

Trim idle gaps

# Trim gaps longer than 2 seconds (default)
ttylog trim session.cast session_trimmed.cast

# Custom gap threshold
ttylog trim session.cast session_trimmed.cast --max-gap 1.5

Export to HTML

# Export as self-contained HTML — no server needed
ttylog export session.cast session.html

Open session.html in any browser. The recording plays automatically. No internet connection required — the player is embedded.

Inspect a recording

ttylog info session.cast

Shows title, command, terminal dimensions, duration, event count, and file size.

.cast format compatibility

ttylog uses the standard asciinema v2 .cast format. Files recorded with ttylog are fully compatible with:

You can also use files recorded with asciinema directly with ttylog trim, ttylog export, and ttylog info.

All commands

ttylog record  OUTPUT         Record a terminal session to a .cast file
ttylog play    SOURCE         Replay a session in the terminal
ttylog export  SOURCE OUTPUT  Export a session as self-contained HTML
ttylog trim    SOURCE OUTPUT  Remove idle gaps from a recording
ttylog info    SOURCE         Show metadata and statistics

record options

--command, -c   Command to run instead of $SHELL
--title,   -t   Session title
--quiet,   -q   Suppress startup banner

play options

--speed, -s   Playback speed multiplier (default: 1.0, range: 0.1–10.0)

trim options

--max-gap, -g   Max idle gap in seconds (default: 2.0)

Windows users

Recording requires a Unix PTY and is not supported natively on Windows. Use WSL2 to record sessions. Playback (ttylog play), export (ttylog export), trim (ttylog trim), and info (ttylog info) all work natively on Windows.

Development

git clone https://github.com/gitwingo/ttylog
cd ttylog
pip install -e .

Support

If ttylog has been useful to you, consider supporting its development:

Connect

• GitHub: @gitwingo
• Reddit: u/gitwingo
• X / Twitter: @gitwingo

License

MIT © gitwingo