How to use the command 'asciinema' (with examples)

The asciinema command is a powerful tool for recording terminal sessions, replaying them, and optionally sharing them on such platforms as asciinema.org. This tool is especially useful for developers who need to demonstrate command-line operations, create tutorials, or simply record their terminal activities for later review. It provides a convenient way to create visual records of what happens in the command line, which can be invaluable for presentations, documentation, or educational purposes.

Use case 1: Associate the local install of asciinema with an asciinema.org account

Code:

asciinema auth

Motivation:

When using asciinema, associating the local installation with your asciinema.org account allows you to upload and manage your recordings online. This integration ensures that you can easily share your sessions with others or keep a backup online. It’s particularly useful if you frequently need to distribute terminal session recordings for collaboration or educational purposes.

Explanation:

• asciinema: The base command to interact with asciinema.
• auth: The subcommand used to authenticate the local asciinema installation with a user account on asciinema.org.

Example output:

Upon executing the command, you typically receive an authorization token or a URL. You’ll need to follow the instructions provided to complete the authentication.

Use case 2: Make a new recording

Code:

asciinema rec

Motivation:

Creating a new recording session allows you to capture everything that transpires in your terminal. This use case is crucial for anyone looking to demonstrate complex command-line processes or troubleshoot issues by reviewing what happened in previous sessions.

Explanation:

• asciinema: The primary command to invoke asciinema functionality.
• rec: Short for “record,” this command initiates a new recording of the terminal session.

Example output:

Once the command is executed, the terminal session is recorded. The control is back to you upon finishing the session with Ctrl+D or by typing exit. You will be prompted to decide whether to save it locally or upload it to asciinema.org.

Use case 3: Make a new recording and save it to a local file

Code:

asciinema rec path/to/recording.cast

Motivation:

Saving a recording to a local file ensures that you have access to the raw data of the session, which can be vital for offline access or further editing with tools like video editors. It’s a straightforward way of managing the recordings on your local system without immediately relying on internet connectivity.

Explanation:

• asciinema: Invokes the asciinema command.
• rec: Initiates recording.
• path/to/recording.cast: Specifies the file path and name where the recording will be stored locally. The .cast extension is conventional for asciinema recording files.

Example output:

After recording, a file named recording.cast is created at the specified location, containing all captured terminal activity.

Use case 4: Replay a terminal recording from a local file

Code:

asciinema play path/to/recording.cast

Motivation:

Replaying a previously recorded session can be pivotal for review and analysis. It allows one to see exactly what occurred during the recording without relying on memory or additional tools to interpret the data. This feature is ideal for troubleshooting, tutorials, or code review sessions.

Explanation:

• asciinema: Command to initiate the tool.
• play: Command to replay a recorded session.
• path/to/recording.cast: Path to the local recording file to be played.

Example output:

The terminal will mimic the exact activities as recorded in the specified file, providing a playback of command execution and terminal output.

Use case 5: Replay a terminal recording hosted on asciinema.org

Code:

asciinema play https://asciinema.org/a/cast_id

Motivation:

Replaying a session stored online ensures accessibility and ease of sharing with others. It enables quick verification of processes or solutions demonstrated in shared sessions without requiring the user to download the file first.

Explanation:

• asciinema: Invokes the replay functionality.
• play: Command to replay a recording.
• https://asciinema.org/a/cast_id: URL of the specific recording on asciinema.org, enabling direct playback of public or shared recordings.

Example output:

Terminal playback will start, showing the session as it happened originally, streaming directly from asciinema.org.

Use case 6: Make a new recording, limiting any idle time to at most 2.5 seconds

Code:

asciinema rec -i 2.5

Motivation:

Recording lengthy terminal sessions often includes periods of inactivity, which may not be useful. Limiting idle time makes the recordings concise and reduces unnecessary data, thus making playback more efficient and focused on the task flow.

Explanation:

• asciinema: The main command for starting a recording.
• rec: Label to record a session.
• -i 2.5: Option specifying the maximum idle time, in seconds, to be captured in the recording. Here, idle periods longer than 2.5 seconds are fast-forwarded.

Example output:

The recording excludes idle times longer than specified, effectively compressing long pauses to expedite review and maintain engagement during playback.

Use case 7: Print the full output of a locally saved recording

Code:

asciinema cat path/to/recording.cast

Motivation:

Sometimes a quick glance at what was executed in a session is needed without playing it. Using cat allows you to view the complete output in a text format, making it easier to analyze or incorporate into documentation or research.

Explanation:

• asciinema: Engages the asciinema tool.
• cat: Command used to print out the content of a recording.
• path/to/recording.cast: Specifies the local file whose content is to be printed.

Example output:

A text output of all commands and results from the session listed sequentially, just as in the recorded session.

Use case 8: Upload a locally saved terminal session to asciinema.org

Code:

asciinema upload path/to/recording.cast

Motivation:

Uploading locally saved sessions to asciinema.org allows for sharing, collaboration, and global access. It supports backup functionality and facilitates public or restricted sharing for community support or team reference.

Explanation:

• asciinema: Calls the asciinema tool.
• upload: Command to send a local file to the cloud service.
• path/to/recording.cast: Identifies the specific local session file to be uploaded.

Example output:

Confirmation of successful upload, often with a URL link to the newly uploaded session on asciinema.org, ready for sharing and access.

Conclusion

The asciinema command is versatile and user-friendly, offering various capabilities for recording, replaying, and sharing terminal sessions. By understanding and using these use cases, users can enhance their command-line interactions significantly, whether for educational, developmental, or collaborative purposes. Asciinema streamlines the process of creating and distributing engaging terminal sessions, contributing substantially to effective digital communication.