---
name: "ttyrec"
section: "1"
platform: "linux"
package: "ttyrec"
version: "1.1.7.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ttyrec"
---

# ttyrec(1)

a tty recorder

## NAME

ttyrec - a tty recorder

## SYNOPSIS

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

- legacy compatibility mode:

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

## OPTIONS

- **-z**, **--uuid** UUID

  specify an UUID (can be any string) that will appear in the ttyrec output file names, and kept with SIGUSR1 rotations (default: own PID)

- **-f**, **--output** FILE

  full path of the first ttyrec file to write to (autogenerated if omitted)

- **-d**, **--dir** FOLDER

  folder where to write the ttyrec files (taken from **-f** if omitted, defaulting to working directory if both **-f** and **-d** are omitted)

- **-F**, **--name-format** FMT

  custom strftime-compatible format string to qualify the full path of the output files, including the SIGUSR1 rotated ones

- **-a**, **--append**

  open the ttyrec output file in append mode instead of write-clobber mode

- **-Z**

  enable on-the-fly compression if available, silently fallback to no compression if not

- **--zstd**

  force on-the-fly compression of output file using zstd, the resulting file will have a '.ttyrec.zst' extension

- **--max-flush-time** S

  specify the maximum number of seconds after which we'll force zstd to flush its output buffers to ensure that even somewhat quiet sessions gets regularly written out to disk, default is 15

- **-l**, **--level** LEVEL

  set 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 session on input timeout after S seconds

- **--warn-before-lock** S

  warn S seconds before locking (see **--lock-timeout**)

- **-k**, **--kill-timeout** S

  kill 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 (see below), this is the default

- **-c**, **--cheatcodes**

  enable cheat-codes (see below)

- **-p**, **--no-openpty**

  don't use openpty() even when it's available

- **-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' (default, allocate a pseudotty if stdin is a tty, uses pipes otherwise)

- **-v**, **--verbose**

  verbose (debug) mode, use twice for more verbosity

- **-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 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)

- ^K^I^L^L^K^I^L^L

  kill your session

### 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.