Use Asciinema and Powersession on Windows

Use Asciinema and Powersession on Windows

• 3 min read
Productivity
asciinema terminal powersession powershell docs

Introduction

I recently became aware of Asciinema when I saw that the Aspire docs are using it to document installing their CLI. As someone who creates a lot of content (or used to, anyway) and docs, this seems like a really useful tool! But it doesn’t “just work” on Windows, so I figured I’d document how to get it working on Windows for future me.

Asciinema Itself

There are basically two parts to Asciinema:

  • Recorder (a CLI) that captures terminal sessions and saves them to .cast files
  • Player (JS library) that renders .cast files on a web page.

You can self-host the JS and .cast files as just static assets.

Unfortunately, the CLI doesn’t support Windows. Which is where other tools come in. These other tools handle recording terminal data into the proper .cast file format, so that you can still use the Asciinema JavaScript player to render them.

PowerSession

There are two ports of the terminal session recorder, a Rust-based one called PowerSession (-rs) and a C# version called just PowerSession, both by the same maintainer. The Rust one is more actively maintained so it’s the one I chose to use.

Installing

To install the PowerSession recorder, just run this:

1

winget install Watfaq.PowerSession

You should get something like this (note this would be animated if I already had a recorder but alas):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

winget install Watfaq.PowerSession
Found PowerSession [Watfaq.PowerSession] Version 0.1.12
This application is licensed to you by its owner.
Microsoft is not responsible for, nor does it grant any licenses to, third-party packages.
This package requires the following dependencies:
  - Packages
      Microsoft.VCRedist.2015+.x64
Downloading https://github.com/Watfaq/PowerSession-rs/releases/download/v0.1.12/PowerSession.exe
  ██████████████████████████████  3.63 MB / 3.63 MB
Successfully verified installer hash
Starting package install...
Path environment variable modified; restart your shell to use the new value.
Command line alias added: "PowerSession"
Successfully installed

Now, to host the files you have options. You can upload and host them on asciinema.org or self-host. I prefer self-host so all of my content stays in one repo.

To host the recordings yourself, you just need this code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

<!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>

You can get the player via npm or as a JavaScript bundle via GitHub release.

Testing It Out

So now that we have PowerSession installed and the asciinema player hosted with my site, let’s test it out. Here’s a quick example showing off my ardalis CLI tool:

Resources

Did you find this helpful? Let me know on BlueSky or subscribe to my newsletter for more content like this!