Documentation

Install or update

With Go 1.27.1 or a Go installation that supports automatic toolchain selection:

go install github.com/termbacktime/termbacktime@latest

Go installs to GOBIN, or your Go workspace’s bin directory. Add it to PATH if necessary. With GOTOOLCHAIN=local, install Go 1.27.1 yourself first.

Without Go, download the installer, inspect it and run it:

sh install.sh

The installer finds the newest published release, including release candidates, directly on GitHub, checks release checksums and installs to ~/.local/bin. Re-run it to update. Choose a release with --version vX.Y.Z or a destination with --bin-dir DIRECTORY. It never rewrites shell profiles or installs Go.

The CLI checks for updates once every 24 hours during normal commands. Run termbacktime --check-update to force a fresh check. Checks fetch one release per page and never install updates automatically. Failed checks leave your command running.

Record locally

termbacktime record --title "A useful discovery"
termbacktime list
termbacktime record --output demo.json
termbacktime record --upload --title "A useful discovery"
termbacktime record --upload --no-save

Exit the shell to finish. By default, local recordings are saved first, even when an upload fails. A crash leaves a recoverable .partial journal that can be opened in the player.

Add --no-save with --upload to use a private temporary recording. Temporary files are removed when the command exits, including after upload failure or cancellation, so no local copy is retained. This mode checks for credentials before recording and cannot be combined with --output.

Capture, finalization and upload preparation use disk-backed files and bounded working buffers. Scanning and review load a bounded recording into memory. Uploads temporarily need extra disk space for the escaped request, which is removed afterward. Finalized recordings gzip-compress terminal events, including local saves and unencrypted uploads. Metadata stays in the JSON envelope; compressed events use its compatible p field. Encryption is a separate option. Active journals remain append-only for recovery. The expanded recording limit stays at 64 MiB. Playback still loads recordings into memory.

Data defaults to ~/termbacktime, with termbacktime.json, recordings/, library/, and private shares/ receipts. Override it with --data-dir or TERMBACKTIME_DATA_DIR. --config independently overrides configuration. Custom output paths are indexed, create missing parents, and never overwrite files.

Use import <paths...> to index recordings without moving them, info <id|path> for metadata, and recover <id|path> to create a new recording from an inactive journal while preserving its source. Missing external files stay listed. list --json supports scripts; title and date filters are available.

termbacktime manage opens an interactive library with recordings on the left and metadata on the right. Press 1 for local files or 2 for your GitHub recording Gists, / to search, Tab to scroll metadata, and ? for help. GitHub listings use your saved authentication and load in small pages with n. Use p to play, s to scan, e to export an offline player, r to recover a journal, or i to import a file. d opens a deletion confirmation: local files and entire Gists are deleted separately, after typing delete. Active recordings are protected.

Every event syncs to disk by default. --sync-interval 1s reduces syncs but leaves up to that interval vulnerable to a machine crash. Successful finalization always syncs.

Review and upload

termbacktime scan <id>
termbacktime redact <id> --rules rules.json
termbacktime upload <cleaned-id>
termbacktime info <id> --show-share-link

Uploads are secret and plaintext by default. Add --public for a public Gist or --encrypt to encrypt the recording with a fresh key. Configure a compatible website with SITE_URL or --endpoint. --no-encrypt remains as a deprecated compatibility option. Existing Gists remain readable.

Scans warn with masked findings and continue uploading unless --fail-on-secrets is selected. The browser Review panel can mask detected secrets or specified literals and remove timestamp intervals. Cleaned copies have new IDs, remove hidden metadata and images, and reset the terminal after cuts. Preview before sharing; the original file remains unchanged.

{"version":1,"literals":["private value"],"detected":true,"intervals":[{"start_ms":12000,"end_ms":18000}]}

Replay and export

To inspect the file itself, use Unpack a recording. It expands packed data and shows source files, metadata, annotations, raw events, and the complete JSON. Event and JSON pages keep large recordings manageable; downloading expanded JSON includes all the data. ANSI sequences remain escaped.

termbacktime play <id> --speed 2 --idle-limit 2s
termbacktime export <id> --format html --output demo.html
termbacktime mark add <id> --at 12s --label "Build passes"

The browser player accepts packed recordings, ordinary JSON and recovery journals. It exports compressed JSON, text, an HTML snapshot, a self-contained offline player, GIF and WebM. Use Unpack for expanded, readable JSON. Video exports are limited to 60 seconds after idle limiting and speed changes, with bounded dimensions. Unicode grapheme widths, ligatures, images and clipboard prompts are optional in the terminal settings dialog (the cog in its header).

Space pauses; arrows jump five seconds; comma and period step events; +/− adjust speed; I/O set loop boundaries and L toggles looping. CLI controls require terminal input and output; --no-interactive disables them. Bookmarks and chapters always use original recording time. Font size, fit-to-width and fullscreen controls are available in the browser.

Offline players work as local files without networking and include annotations. They contain readable recordings. Download JSON or an offline player to retain browser edits. Private uploaded links support copying the current timestamp; keep the complete link because the address bar loses its key after loading.

Share live

termbacktime live --record --ttl 2h

Send the complete URL to viewers you trust. It carries a viewing capability and an encryption key in its fragment. Terminal data is encrypted before reaching Cloudflare. Sessions default to eight hours within the deployment maximum and accept up to 100 read-only viewers. New viewers see the current screen, without previous scrollback.

Keep the original URL if you need to reconnect later. The viewer removes its key from browser history after opening. Old broker links cannot resume sessions on the new service.

Recording is opt-in with --record or --output PATH. The separate private host panel shows viewers and expiry, pauses or resumes updates, locks new admissions, and ends sharing. It holds no terminal encryption key. Existing viewers can reconnect while locked. Pause remains pending until acknowledged; resuming sends a fresh screen. The shell and local recording continue after sharing ends or a reconnect timeout.

termbacktime doctor --json
termbacktime doctor --live --relay-only

Diagnostics show paths, permissions, endpoint compatibility and non-secret authentication status. The opt-in live check creates and cleans up a synthetic room; relay-only verifies TURN delivery.

GitHub authorization

termbacktime auth --open
termbacktime auth --logout

Only Gist uploads require authorization. Anyone with a complete encrypted sharing link can decrypt it. Default plaintext Gists are accessible to anyone who knows their URL.

Platforms and removal

Release binaries support macOS Intel and Apple Silicon; Linux amd64, 386, arm64, ARMv6 and ARMv7; Linux under WSL; and FreeBSD amd64 and 386. Native Windows PTYs are not supported.

Remove the executable from the installation directory to uninstall. Your recordings and ~/termbacktime remain until you remove them yourself.

Migration

Legacy ~/.termbacktime.json automatically migrates when the destination configuration is absent. Credentials and unknown fields are preserved. Existing destinations win, and explicit --config disables migration. Help, version and completion have no filesystem side effects. Existing recording formats remain supported. Live signaling now uses the unified website. The old broker and manual TURN flags have been removed; the service supplies connection credentials. Use --endpoint to select another deployment.

Interactive uploads let you review a suggested title, description and selected computer specifications. metadata.md remains readable on GitHub even when you use encryption. --no-metadata skips review and optional metadata. For automation, supply --description or --metadata-file; otherwise noninteractive uploads omit optional metadata.

Add --dashboard to record or live commands for a shell pane with status and viewer counts outside the recording. Press Ctrl+] for link actions. Direct mode supports terminal features such as inline images.