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

The asciinema command is a tool that allows users to record and replay terminal sessions. It can be used to capture command line activities and share them on asciinema.org. This article provides examples of various use cases of the asciinema command.

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

Code:

asciinema auth

Motivation: By associating the local install of asciinema with an asciinema.org account, users can easily upload recordings to their account and share them with others.

Explanation: This command prompts the user to authorize the local asciinema installation with their asciinema.org account. Once authorized, the user can easily upload their recordings to their account.

Example output:

Please authenticate to upload to asciinema.org
Open the following URL in a web browser to link your install ID:
https://asciinema.org/connect/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Use case 2: Make a new recording

Code:

asciinema rec

Motivation: This use case is useful when users want to record their command line activities for later reference or sharing.

Explanation: This command starts a new recording of the terminal session. Once the recording is finished, the user will be prompted to either upload it to asciinema.org or save it locally.

Example output:

Recording...

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

Code:

asciinema rec path/to/file.cast

Motivation: Saving a recording to a local file allows users to keep a copy for future use or to share it manually.

Explanation: This command starts a new recording of the terminal session and saves it to the specified file path.

Example output:

Recording...

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

Code:

asciinema play path/to/file.cast

Motivation: This use case is helpful when users want to rewatch a previously recorded terminal session.

Explanation: This command replays a terminal recording from the specified local file. It re-executes each command and displays the output just as it was during the original recording.

Example output:

Replaying...

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

Code:

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

Motivation: This use case allows users to replay terminal recordings hosted on asciinema.org without downloading and saving them locally.

Explanation: This command replays a terminal recording from the specified URL on asciinema.org. It re-executes each command and displays the output just as it was during the original recording.

Example output:

Replaying...

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

Code:

asciinema rec -i 2.5

Motivation: Limiting idle time in recordings can help save storage space and make the replay more concise.

Explanation: This command starts a new recording of the terminal session, but it limits inactive time (idle time) to a maximum of 2.5 seconds. If there is no activity for more than 2.5 seconds, the recording will skip that period.

Example output:

Recording...

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

Code:

asciinema cat path/to/file.cast

Motivation: This use case allows users to access the full output of a locally saved recording without playing it.

Explanation: This command displays the entire output of a locally saved terminal recording. It does not re-execute the commands, but only prints the recorded output.

Example output:

Prints the full output of the recording...

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

Code:

asciinema upload path/to/file.cast

Motivation: Uploading a locally saved terminal session to asciinema.org enables users to share the recording with others or embed it in websites.

Explanation: This command uploads a locally saved terminal session to asciinema.org, making it accessible through a unique URL. Once uploaded, the recording can be shared with others or embedded in websites.

Example output:

Uploading...

Conclusion:

The asciinema command is a versatile tool for recording and replaying terminal sessions. It provides various options for capturing, replaying, and sharing command line activities. Whether it’s for reference, collaboration, or demonstration purposes, asciinema makes it easy to capture and share terminal recordings.