asciinema-record - Man Page

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>

Record a terminal session to a file.

Captures all terminal output and optionally keyboard input, saving it for later playback. Supports various output formats, idle time limiting, and session customization options.

Press <ctrl+d> or type 'exit' to end the recording session. Press <ctrl+\> to pause/resume capture of the session.

During the session, the ASCIINEMA_SESSION environment variable is set to a unique session ID.

-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.

Possible values:

• asciicast-v3: Full-featured session format, with timing and metadata (current generation) - https://docs.asciinema.org/manual/asciicast/v3/
• asciicast-v2: Full-featured session format, with timing and metadata (previous generation) - https://docs.asciinema.org/manual/asciicast/v2/
• raw: Raw terminal output, including control sequences, without timing and metadata
• txt: Plain text without colors or control sequences, human-readable

-c,  --command <COMMAND>

Specify the command to execute in the recording session. If not provided, 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. Note that 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". 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.

--overwrite

Overwrite the output file if it already exists. By default, asciinema will refuse to overwrite existing files to prevent accidental data loss. Cannot be used together with --append.

-t,  --title <TITLE>

Set a descriptive 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 and instead, 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. 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.

-h,  --help

Print help (see a summary with '-h')

<FILE>

Output file path

Examples:

 asciinema rec demo.cast
     Records a shell session to a file

 asciinema rec --command "python script.py" demo.cast
     Records execution of a Python script

 asciinema rec --idle-time-limit 2 demo.cast
     Records with idle time capped at 2 seconds

 asciinema rec --capture-input --title "API Demo" demo.cast
     Records with keyboard input and sets a title

 asciinema rec --append demo.cast
     Continues recording to an existing file

 asciinema rec demo.txt
     Records as a plain-text log - output format inferred from the .txt extension

asciinema(1).