Tutorial

Record & share your terminal

A crisp screencast of your terminal is one of the highest-leverage things you can drop into a README, a pull request, or a chat: it shows the tool working instead of describing it. This walkthrough records a pane to an asciinema .cast, plays it back, exports it to a GIF or a video anyone can watch inline, and finally saves a whole session's scrollback to a plain text file for the receipts.

On macOS, ⌘ is the modifier. On Linux, read ⌘ as ⌃ (Ctrl) throughout. Every shortcut here maps to an action you can remap or run from the command palette by name.

1. Record a pane

Focus the pane you want to capture and press ⌘⇧R (toggle_recording). Recording starts immediately, capturing everything that pane prints to an asciinema v2 .cast file. A red ● REC pill shows while capture is running, so you always know you're rolling. Do your thing — run the command, show the failure, walk through the fix — then press ⌘⇧R again to stop.

A .cast is a small, text-based recording of output over time, not a heavy video, so it's cheap to keep around and fast to export later. Capture the take you want now; you'll turn it into a GIF or an MP4 in step 4.

Tip

Don't remember the key? Open the command palette with ⌘⇧P and type record — toggle_recording is right there, along with every other action in this tutorial.

2. Recording is not a macro

These two features sound similar and are easy to mix up, so it's worth being exact before you go further.

Note

Recording and macros are distinct. Recording produces a .cast screencast of everything that happened in a pane — a playback of the session. A macro replays a list of commands you typed, running them again. Use recording to show a session; use a macro to repeat one.

3. Play it back

Before you export anything, watch the take to make sure it's the one you want. If you have the asciinema player installed, play the file straight from the shell:

asciinema play session.cast

It replays at the original pacing, right in your terminal. A .cast can also be embedded on a web page with the asciinema player, which is perfect for docs sites — but for a README, a chat, or a PR you'll usually want a GIF or a video instead, which is the next step.

4. Export to a GIF or video

The fastest path is inside the app. Run Export Recording as GIF or Export Recording as MP4 — both in the File menu, and in the command palette as Export Recording (GIF) / (MP4). It renders your most recent recording in the background and posts a notification when the file is ready, so you can keep working while it encodes. A GIF needs no external tools; an MP4 needs ffmpeg on your PATH.

The same renderer is available from the command line, which is where the real control lives. The output format is chosen by the extension — .gif, .mp4, .mov, or .webm:

# GIF — no extra tools needed
sinclair export session.cast demo.gif

# video — needs ffmpeg on PATH
sinclair export session.cast demo.mp4

Timing and layout are tunable so the clip lands well wherever you paste it:

Option	What it controls
`--fps`	Frame rate of the exported clip (default 30).
`--speed`	Playback speed multiplier.
`--idle-cap`	Collapse long idle gaps (default 2s), so dead air doesn't bloat the file. `--no-idle-cap` keeps real time.
`--tail`	Hold the final frame for this many seconds (default 1), so the ending is readable.
`--font-px`	Font size, in pixels, of the rendered frames (default 16).
`--cols` / `--rows`	Terminal grid size to render at.
`--theme`	Color scheme used for the frames.

On macOS, add --fidelity to render through the app's own gpui text system: the exported frames carry the same ligatures, exact fonts, and crisp box-drawing geometry you see live in the terminal, and --scale sets the device-pixel scale for a retina-sharp result. Other platforms fall back to the bundled software renderer.

# a polished macOS export: fidelity rendering at 30 fps
sinclair export session.cast demo.mp4 --fidelity --fps 30

Tip

Trimming --idle-cap down and nudging --speed up turns a rambling take into a tight demo loop — the kind of GIF that actually reads at the top of a README.

5. Save the whole buffer

Sometimes you don't want a screencast — you want the text. Save Buffer — in the File menu and the command palette as save_buffer, default ⌘S — writes the focused terminal's whole buffer to a plain text file. It captures every scrollback row plus the live screen, independent of what you have selected or scrolled to, so you get the full session rather than just the visible viewport.

A native save dialog opens in the terminal's working directory with a filename suggested from the tab title. Confirm it and the file is written in the background, with a notification to confirm when it's saved. It's the quickest way to attach a complete log to a bug report or paste an entire session into a ticket without scrolling and selecting by hand.

Where to next

Automate your terminal with MCPDrive Sinclair from an agent or a script — including kicking off recordings and exports. CLI referenceEvery sinclair subcommand, including the full sinclair export option list. Triggers, notifications & annotationsSurface what matters while a long session records itself in the background.