rec

A CLI tool to record, replay, and export terminal sessions.

rec captures every command you run in a shell session, then lets you replay them with safety controls or export them to scripts, CI/CD configs, and documentation - turning your terminal workflow into reusable artifacts.

Quick Install

cargo install rec-cli

Pre-built binaries are available for Linux (x86_64, aarch64) and macOS (x86_64, Apple Silicon) on the releases page.

Quick Start

# 1. Set up shell hooks (add to your .bashrc, .zshrc, or config.fish)
eval "$(rec init bash)"   # or: zsh, fish

# 2. Record a session
rec start deploy-server
echo "deploying..."
git pull origin main
docker compose up -d
rec stop

# 3. Replay it
rec replay deploy-server              # interactive replay
rec replay deploy-server --dry-run    # preview without executing
rec replay deploy-server --step       # one command at a time

# 4. Export to a reusable format
rec export deploy-server -f bash -o deploy.sh
rec export deploy-server -f github-action -o .github/workflows/deploy.yml
rec export deploy-server -f dockerfile -o Dockerfile

Features

Recording

rec uses native shell hooks to transparently capture every command, its working directory, exit code, and timing -- with zero overhead when not recording.

• Bash, Zsh, and Fish support with native hook integration
• Crash-safe NDJSON storage with per-command fsync
• Automatic recovery of sessions from crashed processes
• Named sessions with auto-generated names as fallback

Replay

Re-execute recorded sessions with a multi-layered safety system that prevents dangerous commands from causing harm.

rec replay my-session                         # interactive replay
rec replay my-session --dry-run               # preview only
rec replay my-session --step                  # step through one by one
rec replay my-session --skip 3,5              # skip specific commands
rec replay my-session --from 4                # start from command #4
rec replay my-session --skip-pattern "rm*"    # skip by glob pattern
rec replay my-session --cwd                   # use original directories
rec replay my-session --danger-policy skip    # auto-skip dangerous commands
rec replay my-session --danger-policy abort   # abort if any dangerous found
rec replay my-session --danger-policy allow   # allow everything

Safety presets detect destructive commands across three tiers:

• Minimal -- rm -rf /, mkfs, dd, fork bombs
• Moderate -- adds chmod -R 777, DROP TABLE, docker system prune, shutdown, kill -9
• Strict -- adds sudo, curl | sh, pip install, apt remove

Custom patterns can be added via configuration.

Export

Convert recorded sessions into 7 reusable formats:

Smart Parameterization

Auto-detect environment-specific values and replace them with variables for portable output:

rec export my-session -f bash --parameterize
# Detects /home/alice -> $HOME_DIR, alice -> $USERNAME, hostname -> $HOSTNAME

rec export my-session -f bash --param DB_HOST=prod-db.example.com
# Set explicit parameter values

Use {{VAR_NAME}} placeholders directly in your commands during recording for manual parameterization.

Session Management

rec list                          # list all sessions
rec list --tag deploy             # filter by tag
rec list --tag deploy --tag prod --tag-all  # require all tags
rec show my-session               # show session details
rec show my-session --grep "docker"  # filter commands by pattern
rec search "docker compose"       # full-text search across all sessions
rec search --regex "git (push|pull)"  # regex search
rec diff session-1 session-2      # unified diff between sessions
rec rename my-session new-name    # rename a session
rec edit my-session               # edit in $EDITOR (TOML format)
rec tag my-session deploy prod    # add tags
rec tags                          # list all tags with counts
rec tags normalize                # normalize tag casing/format
rec stats                         # aggregate recording statistics
rec delete my-session             # delete a session
rec alias deploy deploy-server    # create a short alias
rec status                        # show current recording status

Import

Import existing shell history or scripts into rec sessions:

rec import deploy.sh                          # auto-detect format
rec import ~/.bash_history --name old-cmds    # import bash history
rec import ~/.zsh_history                     # zsh extended history
rec import ~/.local/share/fish/fish_history   # fish history

Supported formats: Bash scripts, Bash history, Zsh history (plain and extended), Fish history.

Diagnostics

rec doctor        # run 9 diagnostic checks with fix hints
rec doctor --json # machine-readable output
rec demo          # interactive walkthrough of all features

Configuration

rec uses a layered TOML config at ~/.config/rec/config.toml:

rec config --list               # show all settings with sources
rec config --get safety.preset  # get a specific value
rec config --set style.colors never  # set a value
rec config --edit               # open in $EDITOR
rec config --path               # print config file path

[general]
editor = "vim"          # or $EDITOR
shell = "bash"          # or $SHELL

[style]
colors = "auto"         # auto | always | never
symbols = "unicode"     # unicode | ascii
verbosity = "normal"    # quiet | normal | verbose

[safety]
preset = "moderate"     # strict | moderate | minimal
custom_patterns = ["kubectl delete", "terraform destroy"]

Environment Variables

Shell Completions

# Generate at runtime
rec completions bash > ~/.local/share/bash-completion/completions/rec
rec completions zsh > ~/.local/share/zsh/site-functions/_rec
rec completions fish > ~/.config/fish/completions/rec.fish

Generate completions for your shell and add to your shell configuration.

How It Works

1. rec init bash outputs shell hooks that register preexec/precmd functions (Bash uses a bundled bash-preexec library; Zsh and Fish use native hooks)
2. rec start creates a session file and sets a recording lock with PID-based ownership
3. Shell hooks call rec _hook preexec <cmd> before each command and rec _hook precmd <exit_code> after, appending NDJSON lines to the session file with fsync
4. rec stop writes a footer line and releases the lock
5. Sessions are stored as NDJSON at ~/.local/share/rec/sessions/ -- one JSON object per line, crash-recoverable by design

License

Licensed under the MIT License.