Getting started¶

This guide serves as your introduction to asciinema, starting with the basics of recording a terminal with asciinema CLI. We'll cover how to share recordings via asciinema.org, live stream terminal sessions, embed asciinema player on a website, and conclude with instructions for self-hosting asciinema server.

Recording¶

Install the asciinema CLI first. There are several installation options to choose from:

Download static binaryapt (Debian, Ubuntu)pacman (Arch, Manjaro)homebrew (macOS)pipx (asciinema 2.4 only)Other

You can download a pre-built, static binary of the latest version from the releases page.

sudo apt install asciinema

sudo pacman -S asciinema

brew install asciinema

pipx install asciinema

Check the Installation section for all installation options.

Now record your terminal with:

asciinema rec demo.cast

This starts a new recording session, where everything printed to a terminal gets captured and saved to the demo.cast file in asciicast format.

To end the recording session simply exit the shell. This can be done by pressing ctrl+d or entering exit.

Replay your recording with:

asciinema play demo.cast

You can pause/resume by pressing space, or end the playback early by pressing ctrl+c.

See asciinema CLI quick-start guide for more examples.

Replaying a recording in your terminal is handy but not as useful as sharing it with the wider audience on the internet.

You can host your recordings at asciinema.org, which is a public asciinema server instance that provides free hosting for terminal recordings. Hosting your recordings on asciinema.org is completely optional but has many benefits, e.g. easy sharing and embedding.

Upload your recording to asciinema.org with:

asciinema upload demo.cast

The command prints a secret link to the recording page, where you can view it. Feel free to share the link with anyone.

The player component on the recording page is not a typical video player. It's asciinema player, built from the ground up to play terminal sessions. It lets you copy the contents of its terminal view, just like in a regular terminal. Try it: pause the playback, select some lines, copy, paste elsewhere. It's just text after all!

If you'd like to manage your recordings on asciinema.org (set a title, change terminal color theme) you need to link your uploads to your asciinema.org user account. To do it run:

asciinema auth

This command displays a URL, which, when opened in a web browser, authenticates the CLI with your asciinema.org account, ensuring you have access to your uploads.

You can skip this step now, and do it later. However, all recordings not assigned to an account are automatically deleted after 7 days. Run asciinema upload --help and asciinema auth --help for detailed information.

Live streaming¶

In addition to recording terminal sessions to a file, asciinema also supports terminal live streaming. This is useful for live coding sessions, visual monitoring of servers (e.g. with htop), etc.

To start a live stream to asciinema.org:

asciinema stream -r

This provides you with a URL that viewers can visit to watch your terminal session in real-time. The stream begins immediately and continues until you end the session by pressing ctrl+d or entering exit.

This mode of streaming is called "remote streaming", as it sends the stream to a remote asciinema server, which acts as a (public) relay. Remote streaming works with any self-hosted asciinema server, not just asciinema.org.

There's also local streaming mode:

asciinema stream -l

This starts a local web server that lets you access the live stream from your local machine or over LAN. This is purely local, "no-cloud" mode, and no data is sent anywhere.

Run asciinema stream --help for more streaming options. Check out the server streaming guide for technical details about the streaming protocols.

Note

Live streaming requires asciinema CLI 3.0 or newer.

Embedding¶

asciinema player can be embedded on any website by using HTML <script> tag. Embedded player is commonly used on blogs, in project documentation, and in conference talk slides.

All recordings uploaded to asciinema.org can be embedded on a website by using a script snippet provided on the recording's page. It looks like this:

<script async id="asciicast-569727" src="https://asciinema.org/a/569727.js"></script>

To get it, go to a recording page, click on the "Share" button and copy the script from the "Embed the player" section.

The above <script> tag is included right below this very paragraph, resulting in the following player:

If you prefer not to rely on asciinema.org for your embedded demos, you can use the standalone player on your website like this:

<!DOCTYPE html>
<html>
<head>
  ...
  <link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
  ...
</head>
<body>
  ...
  <div id="demo"></div>
  ...
  <script src="/asciinema-player.min.js"></script>
  <script>
    AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'));
  </script>
</body>
</html>

See asciinema player quick-start guide for full setup details.

Self-hosting the server¶

While asciinema.org is the default asciinema server used by the CLI for uploading recordings, you can self-host your own instance if you want full ownership and control over the recordings.

asciinema server is packaged as OCI container image and is available at ghcr.io/asciinema/asciinema-server.

Here's a minimal docker-compose example:

docker-compose.yml

services:
  asciinema:
    image: ghcr.io/asciinema/asciinema-server:latest
    ports:
      - '4000:4000'
    volumes:
      - asciinema_data:/var/opt/asciinema
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: docker.io/library/postgres:14
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 2s
      timeout: 5s
      retries: 10

volumes:
  asciinema_data:
  postgres_data:

Start it with:

docker compose up

Then point asciinema CLI to it by setting ASCIINEMA_API_URL environment variable:

export ASCIINEMA_API_URL=http://localhost:4000

asciinema rec demo.cast
asciinema upload demo.cast

Note that the above configuration should be used only for testing the server locally. See full server self-hosting guide to learn how to set it up properly in a full-featured and secure way.

Generating a GIF¶

On websites where <script> tags are not allowed but <img> tags are, you can use animated GIF files for embedding your demos.

Use agg to create a GIF file from your recording:

agg demo.cast first.gif

See agg usage manual for GIF generation details.

Using asciinema player to present a recording is usually a better choice than a GIF file if you have the option of using <script> tags. Contrary to GIF, the player provides the ability to pause, rewind, copy text, and it always renders the terminal content as sharp as possible on a given display.

Next steps¶

Thank you for taking the first steps with asciinema through this introductory guide. Our goal was to provide you with a clear, high-level overview of the asciinema tools and their usage.

For additional insights and answers, feel free to explore our FAQ section and join the conversation in the #asciinema room on the Matrix network, #asciinema:matrix.org (web client), or #asciinema IRC channel on Libera.Chat (web client).

To stay updated on the latest developments and get useful tips, follow @[email protected] on Mastodon.

Happy recording!