asciinema-stream - Man Page

asciinema stream [-l|--local] [-r|--remote] [-c|--command] [-I|--capture-input] [--capture-env] [-t|--title] [--headless] [--window-size] [--return] [--log-file] [--server-url] [-q|--quiet] [-h|--help]

Stream a terminal session in real-time.

Broadcasts a terminal session live via either the local HTTP server (for local/LAN viewing) or a remote asciinema server (for public sharing). Viewers can watch the session as it happens through a web interface.

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

-l,  --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 listens on an automatically assigned ephemeral port on 127.0.0.1.

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

-c,  --command <COMMAND>

Specify the command to execute in the streaming 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 stream 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.

-t,  --title <TITLE>

Set a descriptive title for the streaming session. This title is displayed to viewers (when doing remote streaming with --remote). For example: --title "Building a REST API". If the server has stream recording enabled then the title will be included in the recording file created on the server side.

--headless

Stream in headless mode without using the terminal for input/output. This is useful for automated or scripted streaming where you don't want asciinema to interfere with the current terminal session. The streamed command will still execute normally and be visible to viewers, 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 streaming 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 streaming dimensions regardless of your current terminal size.

--return

Make the asciinema command exit with the same status code as the streamed session. By default, asciinema exits with status 0 regardless of what happens in the streamed session. With this option, if the streamed 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 streaming issues (connection errors, disconnections, 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 the environment variable ASCIINEMA_SERVER_URL or the 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 stream --local
     Streams a shell session via the local HTTP server listening on an ephemeral port on 127.0.0.1

 asciinema stream --local 0.0.0.0:8080
     Streams via the local HTTP server listening on port 8080 on all network interfaces

 asciinema stream --remote
     Streams via an asciinema server for public viewing

 asciinema stream -l -r
     Streams both locally and remotely simultaneously

 asciinema stream -r --command "ping asciinema.org"
     Streams execution of the ping command

 asciinema stream -r <ID> -t "Live coding"
     Streams via a remote server, reusing the existing stream ID and setting the stream title

asciinema(1).