TTYREC(1)

💖 TTYREC(1) — a tty recorder 💖

okay bestie, so ttyrec is a tty recorder (yes that's the whole NAME section, it's giving minimal and iconic) and it lives in the User Commands corner of the manual. it records your terminal sessions. that's it. that's the girl. ✨

---

🌸 SYNOPSIS 🌸

ttyrec [options] -- <command> [command options]

and then there's the legacy compatibility mode, which is like the older sibling who still lives at home:

ttyrec -e <command> [options] [ttyrec file name]

---

✨ OPTIONS ✨

so many flags, and honestly? every single one of them is useful. no skips, no cuts, we're doing all of them 💅

• -z, --uuid UUID — pick an UUID (and ngl, it can literally be any string, we're not gatekeeping) that'll show up in the ttyrec output file names, and it stays put through SIGUSR1 rotations. default is your own PID.
• -f, --output FILE — the full path of the first ttyrec file we write to. skip it and it gets autogenerated for you 🎀
• -d, --dir FOLDER — the folder where the ttyrec files go. if you don't say, it's taken from -f, and if you don't say either -f or -d, it just defaults to the working directory.
• -F, --name-format FMT — your very own custom strftime-compatible format string to qualify the full path of the output files, SIGUSR1-rotated ones included. bespoke. artisanal. 💜
• -a, --append — open the ttyrec output file in append mode instead of write-clobber mode. no clobbering today, bestie.
• -Z — turn on on-the-fly compression if it's available, and silently fall back to no compression if it's not. no drama, no error message, just vibes.
• --zstd — force on-the-fly compression of the output file using zstd. the resulting file will have a .ttyrec.zst extension.
• --max-flush-time S — the maximum number of seconds after which we'll force zstd to flush its output buffers, so that even somewhat quiet sessions get regularly written out to disk. default is 15.
• -l, --level LEVEL — set the compression level. must be between 1 and 19 for zstd, default is 3.
• -n, --count-bytes — count the number of bytes out and print it on termination. (experimental 👀)
• -t, --lock-timeout S — lock the session on input timeout after S seconds.
• --warn-before-lock S — warn S seconds before locking (see --lock-timeout).
• -k, --kill-timeout S — kill the session on input timeout after S seconds.
• --warn-before-kill S — warn S seconds before killing (see --kill-timeout).
• -C, --no-cheatcodes — disable cheat-codes (they're down below 👇). this is the default.
• -c, --cheatcodes — enable cheat-codes (again, see below 👇).
• -p, --no-openpty — don't use openpty() even when it's available. she said no thank you.
• -T, --term MODE — MODE can be either 'never' (never allocate a pseudotty, even if stdin is a tty, and use pipes to handle stdout/stderr instead), 'always' (always allocate a pseudotty, even if stdin is not a tty) or 'auto' (the default — allocate a pseudotty if stdin is a tty, uses pipes otherwise).
• -v, --verbose — verbose (debug) mode. use it twice for even more verbosity. double it and give it to the next person.
• -V, --version — show version information.
• -e, --shell-cmd CMD — enables legacy compatibility mode and specifies the command to be run under the user's $SHELL -c.

---

🌈 EXAMPLES 🌈

run some shell commands in legacy mode:

ttyrec -e 'for i in a b c; do echo $i; done' outfile.ttyrec

run some shell commands in normal mode:

ttyrec -f /tmp/normal.ttyrec -- sh -c 'for i in a b c; do echo $i; done'

connect to a remote machine interactively:

ttyrec -t 60 -k 300 -- ssh remoteserver

execute a local script remotely with the default remote shell:

ttyrec -- ssh remoteserver < script.sh

record a screen session:

ttyrec screen

---

🦋 FOOTNOTES 🦋

👑 Handled signals:

• SIGUSR1 — close the current ttyrec file and reopen a new one (log rotation).
• SIGURG — lock session.
• SIGUSR2 — unlock session.

---

💅 Cheat-codes (magic keystrokes combinations):

• ^L^L^L^L^L^L^L^L — lock your session (that's 8 CTRL+L's, count 'em 🧚).
• ^K^I^L^L^K^I^L^L — kill your session. (dramatic but valid 💀)

---

🍓 Remark about session lock and session kill:

if we don't have a tty, we can't lock, so -t will be ignored, whereas -k will be applied without warning, as there's no tty to output a warning to. so like, heads up, bestie. 😭

---

and that's the whole page! this one's ttyrec v1.1.5.0, dated June 2019, and it ate, no cap. go record something iconic. 🫶✨🎀