asciinema-record(1)

NAME
asciinema-record - Record a terminal session

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.

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.

OPTIONS

-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

EXTRA
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