asciinema-session - Man Page

asciinema session [-o|--output-file] [-f|--output-format] [-l|--stream-local] [-r|--stream-remote] [-c|--command] [-I|--capture-input] [--capture-env] [-a|--append] [--overwrite] [-t|--title] [-i|--idle-time-limit] [--headless] [--window-size] [--return] [--log-file] [--server-url] [-q|--quiet] [-h|--help] [ENV]

Record and stream a terminal session simultaneously.

Combines the functionality of record and stream commands, allowing you to save a recording to a file while also broadcasting it live to viewers.

Press <ctrl+d> or type 'exit' to end the 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.

-o,  --output-file <PATH>

Save the session to a file at the specified path. Can be combined with local and remote streaming.

-f,  --output-format <FORMAT>

Specify the format for the output file when saving is enabled with --output-file. The default is asciicast-v3. If the output file path ends with .txt, the txt format will be selected automatically unless this option 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

-l,  --stream-local [<IP:PORT>]

Start the local HTTP server to stream the session in real-time. Creates a web interface accessible via browser where viewers can watch the terminal session live. Optionally specify the bind address as IP:PORT (e.g., 0.0.0.0:8080 to allow external connections). If no address is provided, it listends on an automatically assigned ephemeral port on 127.0.0.1. Can be combined with remote streaming and file output.

-r,  --stream-remote [<STREAM-ID|WS-URL>]

Stream the session to a remote asciinema server for public viewing. This allows sharing your session on the web with anyone who has the stream URL. You can provide either a stream ID of an existing stream configuration in your asciinema server account, or a direct WebSocket URL (ws:// or wss://) for custom servers. Omitting the value for this option lets the asciinema server allocate a new stream ID automatically. Can be combined with local streaming and file output.

-c,  --command <COMMAND>

Specify the command to execute in the 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. If the server has stream recording enabled then keyboard input will be included in the recording file created on the server side. 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 session metadata. 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. If the server has stream recording enabled then these environment variables will be included in the recording file created on the server side. 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. Only applies when --output-file is specified.

--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. Only applies when --output-file is specified.

-t,  --title <TITLE>

Set a descriptive title for the session that will be stored in the recording metadata and displayed to stream viewers (when doing remote streaming with --remote). For example: --title "Installing Podman on Ubuntu". If the server has stream recording enabled then the title will be included in the recording file created on the server side.

-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. Only applies when --output-file is specified. Note that this option doesn't alter the original (captured) timing information and 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. Can also be set via the config file option session.idle_time_limit.

--headless

Run the session in headless mode without using the terminal for input/output. This is useful for automated or scripted sessions where you don't want asciinema to interfere with the current terminal session. The session command will still execute normally and be recorded/streamed, but won't be displayed in your local 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 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 session command. By default, asciinema exits with status 0 regardless of what happens in the session. With this option, if the session command exits with a non-zero status, asciinema will also exit with that same status.

--log-file <PATH>

Enable logging of internal events to a file at the specified path. Useful for debugging I/O issues (connection errors, disconnections, file write errors, etc.).

--server-url <URL>

Specify a custom asciinema server URL for streaming to self-hosted servers. Use the base server URL (e.g., https://asciinema.example.com). Can also be set via environment variable ASCIINEMA_SERVER_URL or config file option server.url. If no server URL is configured via this option, environment variable, or config file, you will be prompted to choose one (defaulting to asciinema.org), which will be saved as a default.

-q,  --quiet

Suppress diagnostic messages and progress indicators. Only error messages will be displayed.

-h,  --help

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

Examples:

 asciinema session --output-file demo.cast --stream-local
     Records a shell session to a file and streams it via the local HTTP server listening on an ephemeral port on 127.0.0.1

 asciinema session -o demo.cast --stream-remote
     Records to a file and streams via an asciinema server for public viewing

 asciinema session --stream-local --stream-remote
     Streams both locally and remotely simultaneously, without saving to a file

 asciinema session -o demo.cast -l -r -t "Live coding"
     Records + streams locally + streams remotely, setting the title of the recording/stream

 asciinema session -o demo.cast --idle-time-limit 1.5
     Records to a file with idle time capped at 1.5 seconds

 asciinema session -o demo.cast -l 0.0.0.0:9000 -r <ID>
     Records + streams locally on port 9000 + streams remotely, reusing existing stream ID

asciinema(1).