sloria/doitlive: replay a shell script as if you were typing it

What doitlive is actually for

Live terminal demos fail in boring ways. A command that worked yesterday returns a different error, a package index is slow, a path is wrong, and the presenter narrates a stack trace. The usual fix is to type less and talk more, which makes for a worse demo.

doitlive takes the other route. You write the commands into a file, then run doitlive play session.sh. The tool reads that file and replays the commands in a fake terminal session while typing random characters, so the commands appear on screen at human speed. The README describes it as a tool for live presentations in the terminal, and the demo GIF shows exactly that: a prompt, characters arriving, output appearing.

The audience is narrow and specific. Conference speakers, workshop instructors, developer advocates, and anyone who has to show a shell workflow to a room. If you never present in a terminal, this tool has nothing for you. It does not automate anything, it does not record anything, and it does not make commands faster.

The mechanism: a script file, a fake prompt, and typed characters

The data flow is short. A session file (the README uses session.sh) holds shell commands. doitlive reads that file, and for each command it prints the characters one at a time into the terminal, then runs the command and shows its output. The examples/ directory in the repository ships two session files, walkthrough.sh and python_and_ipython.sh, which is a useful hint about intended use: shell walkthroughs and Python or IPython sessions.

The typing effect is the product. The README's quickstart ends with the instruction to type like a madman, which is the joke and also the point: you are free to keep talking while the tool does the typing.

The dependency list in pyproject.toml is small and worth reading. doitlive depends on click (>=8.0,<9), click-completion, and click-didyoumean. That means the command surface is a click application, and the CLI entry point is declared as doitlive = doitlive.cli:cli. There is no terminal emulator library in the dependency list, so the fake session is built from ordinary terminal output rather than a pty abstraction. That keeps the install light, and it also explains why the tool is a replay layer rather than a shell replacement.

Installing doitlive and running a first session

The README gives two install paths. On macOS with Homebrew, update first and then install the formula. The formula lives in homebrew-core, so no tap is needed.

brew update
brew install doitlive

With pip, the package name matches the project name. Python 3.10 or newer is required, per requires-python in pyproject.toml.

pip install doitlive

A first session is three steps. Create a file called session.sh, fill it with bash commands, and play it.

doitlive play session.sh

You should see the commands appear as if typed, followed by their output. The README's quickstart is exactly this sequence: create session.sh, run doitlive play session.sh, then type like a madman. If you want to see a longer example before writing your own, the repository's examples/walkthrough.sh is the file to read.

Where doitlive stops being the right tool

The most important limitation is in the name of the output: it is a replay. doitlive prints the commands and then runs them, so the output you see is whatever the machine actually produces at that moment. If a command depends on a service that is down, a file that moved, or a package that changed, the demo shows the failure. The tool does not cache output and the README does not document any way to pre-record results.

The second limitation is that the README and the repository layout document very little beyond install and play. Rollback, session file syntax beyond plain shell commands, timing controls, and what happens when a command in the session file is interactive are not covered in the README. The docs site at doitlive.readthedocs.io is where that would live, and it is the place to check before you build a talk around a feature you have not confirmed.

The third is environmental. It is a Python package, so you need Python 3.10 or newer on the presenting machine, or the Homebrew formula on macOS. A locked-down conference laptop with neither is a dead end. If your demo must run somewhere you cannot install packages, doitlive is the wrong choice.

Finally, do not confuse this with a recorder. It plays a file you wrote. It does not capture what you typed, and it will not help you reconstruct a session after the fact.

doitlive compared with a real shell and with HackerTyper-style toys

The README itself points at two related projects, HackerTyper and PlayerPiano, and the difference matters. Those tools produce the typing effect and nothing else: the characters are decoration. doitlive runs the commands after typing them, so the output on screen is real output from the machine. That is the whole distinction, and it is why doitlive belongs in a technical talk and HackerTyper belongs in a joke.

Against a plain shell, the trade-off runs the other way. A shell gives you real interactivity, real history, and the ability to improvise. doitlive gives you a fixed script and the appearance of improvisation. If your demo depends on reacting to what the audience asks, a shell plus a well-practiced set of commands is better. If your demo depends on the commands being right, doitlive removes the typing as a source of failure.

The README credits Armin Ronacher's click library for making the tool quick to implement, and the dependency list confirms the CLI is built on click. That is the same stack as many Python command-line tools, so if you already know click, the command structure will look familiar.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-08. The project is MIT licensed, and pyproject.toml declares license = { file = "LICENSE" } with the MIT classifier, so the terms are permissive and the LICENSE file is the authority. Nothing here is legal advice; read the LICENSE file if the distinction matters to your organisation.

On upgrade cost, the constraints visible in pyproject.toml are the ones to watch. The version is 5.2.1, the click pin is >=8.0,<9, and Python support starts at 3.10 with classifiers through 3.14. A major click 9 release would require a change before doitlive could follow, which is a normal cost for a small CLI. The test extra pulls pytest and IPython>=8, and the dev extra adds tox and pre-commit, so contributing or running the suite locally means installing Python dependencies rather than just the binary.

For a presentation tool, the practical upgrade risk is low. The session file format is shell commands, so your content survives most version changes. The thing that can break is the CLI surface, and the changelog at doitlive.readthedocs.io/en/latest/changelog.html is the file to read before upgrading before a talk.

Editorial conclusion

Adopt doitlive if you give terminal demos and want the commands already written down, run with pip install doitlive or brew install doitlive, and check that your Python is 3.10 or newer. Do not adopt it if you need the output to be real, if you are presenting on a machine where you cannot install packages, or if you want a recorder that captures what you actually ran. Before you rely on it in front of an audience, verify two things on the target machine: that doitlive play session.sh finds your file and that the session file's commands still produce the output you expect, because doitlive replays the text and does not check the result.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. sloria/doitlive on GitHub