# Output Recording
Record terminal output for later review, debugging, or sharing with support for multiple formats and built-in sensitive data redaction.
## Table of Contents
- [Overview](#overview)
- [Recording Formats](#recording-formats)
- [Starting a Recording](#starting-a-recording)
- [Configuration](#configuration)
- [Security: Sensitive Data Redaction](#security-sensitive-data-redaction)
- [File Locations](#file-locations)
- [Playback](#playback)
- [Asciicast Format Details](#asciicast-format-details)
- [Related Documentation](#related-documentation)
## Overview
Output recording captures terminal output in multiple formats:
```mermaid
graph TD
Session[Terminal]
Logger[Output Recorder]
Plain[Plain Text .txt]
HTML[HTML .html]
Asciicast[Asciicast .cast]
Session -->|PTY Output| Logger
Logger --> Plain
Logger --> HTML
Logger --> Asciicast
class Session primary
class Logger active
class Plain neutral
class HTML data
class Asciicast external
classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
classDef data fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
classDef external fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
```
## Recording Formats
| **Plain Text** | `.txt` | Raw text, no formatting | Simple logs, grep-able output |
| **HTML** | `.html` | Styled HTML page | Browser viewing, sharing |
| **Asciicast** | `.cast` | asciinema-compatible | Playback, sharing online |
| **Asciicast v3** | `.cast` | v3 with inline graphics as base64 `g` events | Recordings with images (Sixel/iTerm2/Kitty) |
### Plain Text
- Strips all ANSI escape sequences
- Captures only printable text
- Smallest file size
- No color or styling information
### HTML
- HTML-escaped text in a styled page (ANSI colors are not converted)
- Viewable directly in browsers
- Dark background with monospace font
- Includes CSS styling
### Asciicast (Default)
- asciinema v2 format
- Supports timing-accurate playback
- Records terminal output events only; keyboard input is never captured
- Can be shared on asciinema.org
### Asciicast v3 (Opt-in)
- Everything v2 records, plus a `g` (graphics) event per inline image
(Sixel/iTerm2/Kitty) with base64 pixel data and placement metadata
- Opt-in only: set `session_log_format: asciicast_v3` in config.yaml or pick
"Asciicast v3 (graphics)" in Settings → Advanced → Logging
- **Security:** `g`-event pixel data bypasses every credential-redaction layer
(see [Security](#security-sensitive-data-redaction)) — a credential rendered
as an image is captured verbatim. Only enable where that is acceptable.
- Text-only fallback: if the terminal is unavailable at finalization, the log
serializes without `g` events and stays a valid v3 file
## Starting a Recording
### Method 1: Hotkey Toggle
Press `Cmd+Shift+R` (macOS) or `Ctrl+Shift+R` (Windows/Linux) to toggle recording.
**Visual Feedback:**
- Toast notification: `⏺ Recording Started` or `⏹ Recording Stopped`
### Method 2: CLI Flag
Start par-term with output recording enabled:
```bash
par-term --log-session
```
### Method 3: Auto-Logging
Enable automatic recording for every tab in your configuration:
```yaml
# ~/.config/par-term/config.yaml
auto_log_sessions: true
```
### Method 4: Settings UI
1. Press `F12` to open Settings
2. Navigate to **Advanced** tab
3. Check **Record every tab's output automatically**
## Configuration
Add these options to `~/.config/par-term/config.yaml`:
```yaml
# Enable/disable automatic recording for every tab
auto_log_sessions: false
# Log format: plain, html, asciicast (default), or asciicast_v3
session_log_format: asciicast
# Custom log directory (default: ~/.local/share/par-term/logs/)
session_log_directory: ~/.local/share/par-term/logs/
# Redact passwords detected at common prompts (enabled by default)
session_log_redact_passwords: true
```
### Settings UI Options
The Advanced > Logging page in Settings provides:
| **Record every tab's output automatically** | Auto-start recording for new tabs |
| **Log format** | Dropdown: Plain Text, HTML, Asciicast (asciinema) |
| **Log directory** | Path to log storage directory |
| **Archive recording on tab close** | Ensure clean file write on close |
| **Redact passwords in recordings** | Detect password prompts and replace input with redaction marker |
## Security: Sensitive Data Redaction
Recordings capture raw terminal output, which may include passwords and other credentials. Keyboard input is never recorded. When `session_log_redact_passwords` is enabled (default), the logger applies two layers of heuristic protection:
### Input Redaction (Password Prompts)
- Monitors terminal output for common password prompt patterns
- Replaces any input the logger receives during a detected prompt with `[INPUT REDACTED - echo off]` until Enter is pressed
- Detects prompts like: `password:`, `[sudo]`, `passphrase:`, `enter pin:`, `api key:`, `token:`, etc.
- Also supports MFA/2FA prompts, SSH/GPG passphrases, database credentials, and cloud/vault tokens
### Output Redaction (Credential Patterns)
The logger also monitors **terminal output** for lines that appear to contain sensitive credentials being printed (e.g., `export API_KEY=...`, `aws_secret_access_key = ...`). Matching lines are replaced with:
```
[OUTPUT REDACTED - sensitive data heuristic matched]
```
Detected output patterns include:
- Shell variable exports for credential names (`export aws_secret`, `export api_key`, etc.)
- AWS credential file patterns (`aws_access_key_id`, `aws_secret_access_key`)
- Private key markers (`-----BEGIN RSA PRIVATE KEY-----`, etc.)
- Generic `api_key=`, `secret_key=` assignments
- CI/CD and service tokens: `GITHUB_TOKEN=`, `HEROKU_API_KEY=`, `npm_token=`, `pypi_token=`, `gitlab_token=`, `circleci_token=`
- Bearer token headers: `Bearer <token>`
> **Note:** Plain-text logs begin with a header warning documenting known redaction limitations — not all credential formats can be detected.
### Limitations
> **Warning:** Redaction is heuristic-based and cannot guarantee detection of all sensitive data. Credentials may still be captured in cases such as:
> - Custom or localized password prompts not in the pattern list
> - Credentials pasted into the terminal (no echo-suppress signal)
> - API keys or tokens typed as command arguments
> - Applications that suppress echo without emitting a matching prompt string
> - Base64-encoded or obfuscated secrets
> - Values printed without recognizable key names
> - **Asciicast v3 `g` events:** embedded image pixels are opaque to every
> redaction layer — a credential rendered as an image (QR code, TUI
> screenshot) is captured verbatim. This gap applies to the
> `asciicast_v3` format only.
**Recommendation:** If you regularly work with sensitive credentials, disable output recording for those tabs. Do not rely solely on redaction as a security control.
## File Locations
**Default Directory:** `~/.local/share/par-term/logs/`
**File Naming:** `session_YYYYMMDD_HHMMSS.{extension}`
**Example:** `session_20260202_143025.cast`
The directory is automatically created if it doesn't exist.
## Playback
### Asciicast Files
Play back `.cast` files using asciinema:
```bash
# Install asciinema
brew install asciinema # macOS
apt install asciinema # Debian/Ubuntu
# Play a recording
asciinema play session_20260202_143025.cast
# Play at 2x speed
asciinema play -s 2 session_20260202_143025.cast
```
**Share Online:**
```bash
asciinema upload session_20260202_143025.cast
```
### HTML Files
Open directly in any web browser:
```bash
open session_20260202_143025.html # macOS
xdg-open session_20260202_143025.html # Linux
```
### Plain Text Files
View with any text editor or terminal:
```bash
cat session_20260202_143025.txt
less session_20260202_143025.txt
```
## Asciicast Format Details
The `.cast` files follow the asciinema v2 specification:
**Header (first line):**
```json
{
"version": 2,
"width": 80,
"height": 24,
"timestamp": 1770042625,
"title": "Tab 1 - 2026-02-02 14:30:25",
"env": {
"TERM": "xterm-256color",
"COLS": "80",
"ROWS": "24"
}
}
```
**Event Lines:**
```json
[0.0, "o", "$ "]
[0.7, "o", "\r\n"]
[1.0, "o", "file1.txt file2.txt\r\n"]
```
**Event Types:**
- `o` - Output (terminal -> user)
- `i` - Input (user -> terminal)
- `r` - Resize (terminal dimensions changed)
- `m` - Marker (annotation)
par-term writes `o` (output), `i` (input — subject to password/echo redaction), and `r` (resize) events. `m` (marker) is part of the asciinema v2 specification and is handled by the writer, but par-term never constructs one today.
In **asciicast v3**, event times become per-event relative intervals, resize payloads become `"COLSxROWS"` strings, and the `g` event carries a JSON object per inline graphic (protocol, placement, dimensions, base64 `data`). `g` events are keyed to the moment each image entered the terminal's graphics store, re-anchored to the recording start so they stay aligned with the text stream.
## Related Documentation
- [CONFIG_REFERENCE.md](../CONFIG_REFERENCE.md) - Configuration options reference
- [KEYBOARD_SHORTCUTS.md](../guides/KEYBOARD_SHORTCUTS.md) - Recording hotkey
- [README.md](../../README.md) - Project overview