Record a terminal session that shows every key you press
To record a terminal session where viewers see every key, record the screen as video with an on-screen key display set to show all keys, not only shortcuts, including Return, Tab and Control combinations. Text recorders, such as the script command built into macOS, play back what the terminal printed rather than the keys you pressed, so Tab completion, Control-R and the arrow keys leave only their results behind. Make the terminal’s text bigger before you start, and keep anything secret out of the take.
Why terminal demos lose the keys
Most of the speed in a shell comes from keys that print nothing. You press Control-A and the cursor jumps to the start of the line. You press Control-R, type three letters, and a long command from last week appears. You press Tab twice and a file name finishes itself. Viewers see the result each time, but not what caused it, and the command line is exactly where people copy what you do.
These are zsh’s defaults in its emacs mode, which is what zsh uses on a Mac unless your EDITOR or VISUAL variable contains “vi” or your setup turns on vi mode:
| Keys | What it does in zsh |
|---|---|
| ⌃A | Move to the start of the line |
| ⌃E | Move to the end of the line |
| ⌃R | Search back through your history |
| ⌃W | Delete the word before the cursor |
| ⌃U | Delete the whole line |
| ⌃L | Clear the screen |
| ⌃C | Stop the running command |
| Tab | Complete a command or file name |
| ↑ | Bring back the previous command |
None of them has a menu item, so nothing on screen names them. Terminal shortcuts on a Mac covers more of them, if you want viewers to learn them as well as see them.
Text recordings versus video
There are two ways to record a terminal, and they solve different problems.
Text recordings. macOS includes script, which saves a terminal session to a file. Run script -r demo.rec to record with timing, work as usual, type exit to stop, and script -p demo.rec plays it back in real time. Third-party recorders such as asciinema do the same job and can be shared on the web, with text viewers can select and copy. What viewers get back is what the terminal showed. A key that changed nothing visible, or changed it without saying why, is not in the playback. The file can hold more than the playback shows, though: script -r also stores the keys you send, and script -k logs keys in a plain typescript, so either can contain something typed at a hidden password prompt. Keep those files private, and share a clean take instead.
Video. A screen recording with a key display shows the cause and the effect together and plays anywhere. Viewers cannot copy the text out of it, so put the commands in the description or a README next to the video.
For a tutorial where the keys are the lesson, record video. For a reference people will copy from, a text recording or a written list is better, and the two work well together.
Set up a key display for a terminal
A key display set to shortcuts only will miss most of a terminal demo, so change what it shows:
- Show every key. In Typebar, set the pill to show everything, with Return and Tab included. Typing gathers into one chip, and Control combinations show as their keys, so ⌃R appears where it happened.
- Let it name the terminal’s own shortcuts. The pill names each shortcut with the name it has in the app’s menus. In Terminal, Command-K is Edit > Clear to Start, so it shows as “⌘K Clear to Start”, and Option-Command-K is Clear Scrollback.
- Switch setups by app. In Settings > Profiles, a profile can switch on by itself when chosen apps are in front. Make one for your terminal that shows every key, and keep a shortcuts-only setup for everything else.
Hold Command for a moment while Terminal is in front and Typebar’s keys relabel with Terminal’s menu commands. Typebar also has a hand-made Terminal pack for shortcuts the menus leave out, and it reads your own keybindings from the settings files of iTerm2, kitty, Ghostty and WezTerm.
Then make the text big enough to read. In Terminal, View > Bigger (Command-Plus) enlarges the font in the front window, and View > Default Font Size (Command-0) puts it back. Size the pill against that text.
Keep secrets out of the recording
A shell’s password prompt hides what you type from the terminal, not from the keyboard. Unless the terminal turns on secure input, a key display can still see the letters, even though the shell prints nothing.
- When macOS marks input as secure, Typebar shows nothing typed, and the pill says “Typing hidden in a password field”.
- Hide letters, in Typebar’s Privacy settings, shows shortcuts and special keys but turns letters into dots. Turn it on for any part of a demo where you type a token, a host name or anything else private.
- Pause, from the menu or its own shortcut, stops everything showing until you resume.
Terminal also has Secure Keyboard Entry in its app menu, under Terminal. While it is on, no other app can see what you type in Terminal, which includes your key display, so the keys disappear from the recording. That is its job. If you leave it on for daily work, switch it off for the take and back on afterwards, and keep real secrets out of the session entirely. Why some apps go blank to key displays explains secure input in more detail.
Before you record, also clear what is already on screen and in the scrollback: Edit > Clear Scrollback (Option-Command-K) in Terminal. Old output, environment variables and history can show a secret without a single key being pressed.
Record it
- Open the terminal window at the size you want, with the font enlarged.
- Put the pill next to the window, in the area you will record. Drag it by its handle.
- Press Command-Shift-5 (⇧⌘5), choose Record Selected Portion, and drag the box around the window and the pill, or record the entire screen.
- Click Record. Stop with the Stop button in the menu bar or Command-Control-Escape.
The pill appears in screen recordings like any other window, so a recorder set to capture only the terminal’s window will leave it out. Capture the screen or an area that includes it.
Type slower than you normally would, and leave a beat after Return so viewers can read the output before the next command. Clear the screen with Control-L or Command-K between sections, so each one starts at the top. Making a coding screencast viewers can follow has more on pacing.
Questions
Can script or asciinema show the keys I press?
Their playback shows what the terminal printed. Keys that print nothing, such as Tab completion, Control-A or the arrow keys through history, show up only as their results. For the keys themselves, record video with a key display.
Why do my keys vanish when Terminal is in front?
Usually because Secure Keyboard Entry is on. Open the Terminal menu and look for a checkmark next to it. Other terminals, such as iTerm2, have a similar option.
Does this work in iTerm2, Ghostty and other terminals?
Yes. A key display shows what you press whatever app is in front, and Typebar reads your own keybindings from iTerm2, kitty, Ghostty and WezTerm for its cheatsheets.
Typebar is $9 once for up to 5 Macs, and free for 24 hours with everything on.