asciinema-record(1) General Commands Manual 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] 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 or type 'exit' to end the recording session. Press 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: o asciicast-v3: Full-featured session format, with timing and metadata (current generation) - https://docs.asciinema.org/manual/asciicast/v3/ o asciicast-v2: Full-featured session format, with timing and metadata (previous generation) - https://docs.asciinema.org/manual/asciicast/v2/ o raw: Raw terminal output, including control sequences, without timing and metadata o 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') 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 record asciinema-record(1)