asciinema-record(1)

📦
version 3.2.1 · 2 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

💖 NAME 💖

okay so, bestie: asciinema-record — record a terminal session. That's the whole name section, it's short and it ate. You're reading the asciinema-record(1) page from the General Commands Manual (section 1, and yes the entry itself is named record — iykyk).

✨ SYNOPSIS ✨

asciinema record [-f|--output-format] [-c|--command]
[-I|--capture-input] [--capture-env] [-a|--append] [--overwrite]
[-t|--title] [-i|--idle-time-limit] [--headless] [--window-size]
[--return] [--log-file] [-q|--quiet] [-h|--help] <FILE>

🎀 DESCRIPTION 🎀

Record a terminal session to a file. Literally that's it, that's the job. 💅

It captures all terminal output and optionally keyboard input, saving everything so you can play it back later. It's giving "screen recording but for your terminal" — and it supports various output formats, idle time limiting, and session customization options. Obsessed.

  • Press Ctrl+D or type exit to end the recording session. 🫶
  • Press Ctrl+</kbd> to pause/resume capture of the session. ✨
Heads up: during the session, the ASCIINEMA_SESSION environment variable is set to a unique session ID. No cap.

🔥 OPTIONS 🔥

like, all of them. no skips, no gatekeeping. 👑

  • -f, --output-format=FORMAT — specify the format for the output file. The default is asciicast-v3. If the file path ends with .txt, the txt format will be selected automatically — unless --output-format is explicitly specified (the flag always wins, main character energy).

Possible values:

  • -c, --command=COMMAND — specify the command to execute in the recording session. If you don't provide one, asciinema will use your default shell from the $SHELL environment variable. This can be any command with arguments, for example: --command "python script.py" or --command "bash -l". Can also be set via the config file option session.command. 🐚
  • -I, --capture-input — enable recording of keyboard input in addition to terminal output. When enabled, both what you type and what appears on the screen will be captured.
⚠️ fr fr warning: sensitive input like passwords will also be recorded when this option is enabled. 💀

Can also be set via the config file option session.capture_input.

  • --capture-env=VARS — specify which environment variables to capture and include in the recording metadata. This helps ensure the recording context is preserved, e.g. for auditing. Provide a comma-separated list of variable names, for example: --rec-env "USER,SHELL,TERM" (that's exactly how the example is spelled in the docs, copy-paste bestie). If not specified, only the SHELL variable is captured by default. Can also be set via the config file option session.capture_env. 🦋
  • -a, --append — append the new session to an existing recording file instead of creating a new one. This allows you to continue a previous recording session. The timing will be adjusted to maintain continuity from where the previous recording ended. Cannot be used together with --overwrite — pick a side. ✌️
  • --overwrite — overwrite the output file if it already exists. By default asciinema will refuse to overwrite existing files, to prevent accidental data loss (it's protecting you, and honestly? valid). Cannot be used together with --append.
  • -t, --title=TITLE — set a title that will be stored in the recording metadata. This title may be displayed by players and is useful for organizing and identifying recordings. For example: --title "Installing Podman on Ubuntu". 🎀
  • -i, --idle-time-limit=SECS — limit the maximum idle time recorded between terminal events to the specified number of seconds. Long pauses (such as when you step away from the terminal) will be capped at this duration in the recording, making playback more watchable. For example, --idle-time-limit 2.0 will ensure no pause longer than 2 seconds appears in the recording.
🧠 note that this option doesn't alter the original (captured) timing information — instead, it embeds the idle time limit value in the metadata, which is interpreted by session players at playback time. This allows tweaking of the limit after recording. Iconic behaviour, honestly.

Can also be set via the config file option session.idle_time_limit.

  • --headless — record in headless mode without using the terminal for input/output. This is useful for automated or scripted recordings where you don't want asciinema to interfere with the current terminal session. The recorded command will still execute normally, but asciinema won't display its output in your terminal. Headless mode is enabled automatically when running in an environment where a terminal is not available. 🧚
  • --window-size=COLSxROWS — override the terminal window size used for the recording session. Specify dimensions as COLSxROWS (e.g., 80x24 for 80 columns by 24 rows). You can specify just columns (80x) or just rows (x24) to override only one dimension. This is useful for ensuring consistent recording dimensions regardless of your current terminal size. 📐
  • --return — make the asciinema command exit with the same status code as the recorded session. By default, asciinema exits with status 0 regardless of what happens in the recorded session. With this option, if the recorded command exits with a non-zero status, asciinema will also exit with the same status. 💯
  • --log-file=PATH — enable logging of internal events to a file at the specified path. Useful for debugging recording issues. 🔍
  • -q, --quiet — suppress diagnostic messages and progress indicators. Only error messages will be displayed. Peace and quiet, slay. 🤫
  • -h, --help — print help (see a summary with '-h'). 🫶
  • <FILE> — output file path.

🌈 EXTRA 🌈

Examples, aka the fun part. Copy these, they're literally ready:

asciinema rec demo.cast

Records a shell session to a file. the classic. ⭐

asciinema rec demo.cast

asciinema rec --command "python script.py" demo.cast

Records execution of a Python script. 🐍

asciinema rec --command "python script.py" demo.cast

asciinema rec --idle-time-limit 2 demo.cast

Records with idle time capped at 2 seconds. no more five-minute "brb" gaps in your cast. 😭

asciinema rec --idle-time-limit 2 demo.cast

asciinema rec --capture-input --title "API Demo" demo.cast

Records with keyboard input and sets a title. 👑

asciinema rec --capture-input --title "API Demo" demo.cast

asciinema rec --append demo.cast

Continues recording to an existing file. the way that continuity works… 🦋

asciinema rec --append demo.cast

asciinema rec demo.txt

Records as a plain-text log — output format inferred from the .txt extension. 🍓

asciinema rec demo.txt

and that's the page, bestie 🫶 — this has been the record entry, asciinema-record(1), living in your General Commands Manual (section 1). go forth and record something iconic. 💖✨🎀

📦 where this page comes from