Documentation

Install

With Go, or automatic toolchain selection:

go install github.com/termbacktime/termbacktime@latest

Add GOBIN or Go's bin directory to PATH. Choose releases with @vX.Y.Z; checkouts support go install ..

Or download the installer, review it, and run:

sh install.sh

The installer verifies checksums, installs to ~/.local/bin, and leaves shell profiles unchanged. Re-run to update. --version vX.Y.Z selects a tag; --bin-dir DIRECTORY selects a destination. The newest release can be a prerelease.

Checking for updates

Normal CLI commands check once a day. A notice appears after a fresh successful check; nothing updates automatically.

termbacktime --check-update

Record a session

termbacktime record --title "Debugging a test"
termbacktime record --output demo.tbt
termbacktime record --output tests.tbt -- go test ./...
termbacktime record --dashboard --shell /bin/bash
termbacktime record --upload --no-metadata

Interactive recordings load your login-shell setup; exit finishes and allows upload even after a failed command. Single-command recordings preserve exit status and upload only on success. Files default to ~/termbacktime/recordings/; existing output files are never overwritten.

--dashboard shows uncaptured status. Ctrl+] opens controls; Esc returns. --shell selects a shell; --no-metadata omits computer details.

Command capture is enabled for recordings and saved live sessions on Bash 4.4+, zsh 5.8+, and fish 3.6+. It records submitted commands, working directories, timing, and exit status using temporary session hooks. --no-command-capture disables it independently of --no-metadata. Unsupported shells rely on transcript extraction; filtered Bash history produces gaps. Only the outer shell is captured: nested shells, SSH, editor changes, program input, and environment setup need manual steps.

--upload shares after recording and keeps the local copy. Add --no-save to use temporary files, deleted even after failure or cancellation. It requires --upload and cannot be combined with --output or queueing.

Manage your recordings

termbacktime manage
termbacktime list --json
termbacktime import /path/to/session.tbt
termbacktime info demo.tbt

Choose Local, Gists, or Repository. Imports stay in place. Use IDs, unambiguous prefixes, or paths.

“Checking” means validation is pending. Enter previews metadata; v verifies chunks with cancelable progress.

Sort, filter, and verify

termbacktime list --sort title --order asc
termbacktime list --status ready,partial --pinned=false --uploaded --json
termbacktime list --sort size --uploaded=false --title demo
termbacktime list --after 2026-01-01 --before 2026-12-31
termbacktime info demo.tbt --quick

Sort by date, title, duration, or size. Title defaults ascending; other sorts descending. Dates are inclusive UTC dates. Statuses are ready, recording, partial, missing, unsupported, and invalid. Status selections combine with OR; different filters combine with AND.

GitHub filters cover loaded pages; n loads more. Badges show pins/upload counts. a shows receipts; v checks availability; c/o copies/opens complete private links. Receipts describe upload history without verifying current content.

Upload from the manager

Press u to review storage, visibility, encryption, title, description, and computer metadata. Browsing leaves upload preferences unchanged.

Choose Upload now or Add to queue. Progress and the resulting link stay inside the manager; c/o copies/opens it. Esc cancels review or requests cancellation. A request already sent may have completed; reconciliation avoids blindly creating another publication.

Review and upload

termbacktime auth --storage repo --open
termbacktime scan demo.tbt
termbacktime upload demo.tbt
termbacktime auth --storage gist --open
termbacktime upload demo.tbt --storage gist --public
termbacktime upload demo.tbt --encrypt --fail-on-secrets

Repository setup guides you through creating a public TBT-Recordings under your personal account. Install the GitHub App with Only select repositories → TBT-Recordings, granting Contents read/write and Metadata read. Gists have a separate login.

Uploads use the last confirmed review choice, otherwise Repository. --storage repo|gist overrides one invocation. Repository publications are always public; --public=false is rejected there. Gists default to secret and plaintext, meaning anyone with the URL can read them. --public makes a Gist public.

--encrypt protects content on either destination, but approved README metadata remains readable on GitHub. Keep the complete link: its fragment carries the key. Retrieve saved links with termbacktime info demo.tbt --show-share-link.

Interactive review chooses title, description, and computer categories. --no-metadata skips review and omits optional metadata. Noninteractive uploads omit computer details unless explicitly supplied. For automation, use --description or --metadata-file, for example:

{ "version": 1, "title": "Demo", "description": "Build walkthrough" }

For Gist automation, use TERMBACKTIME_TOKEN or auth --token-stdin. auth --logout removes saved logins; --storage selects one. auth --refresh-client-id refreshes discovery after changing sites or GitHub apps.

Remove something private

Scanning masks findings. --fail-on-secrets blocks uploads with findings. Review recordings yourself too.

Save rules.json to remove detected secrets, literals, or time intervals:

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

termbacktime redact demo.tbt --rules rules.json --output cleaned.tbt
termbacktime play cleaned.tbt
termbacktime upload cleaned.tbt

Redaction creates a new recording, preserves the original, and removes hidden links, clipboard requests, and images. Replay the result before sharing.

Queue uploads for later

termbacktime upload demo.tbt --queue
termbacktime queue list --json
termbacktime queue run
termbacktime queue retry JOB_ID
termbacktime queue cancel JOB_ID

Runs process their initial snapshot; later jobs wait for another explicit run. In the manager queue, R/C/X requeue an eligible failed/canceled job, cancel it, or stop the runner. PgUp/PgDn scrolls job details. Esc returns to browsing while uploads continue; quitting stops the runner. “Needs attention” jobs are reconciled before another creation attempt.

Play and export

Open a shared link, choose a local file, or browse public repositories. Local files stay in your browser; encrypted shares require their complete links.

The player provides play/pause, seeking, stepping, speed, loops, recording details, and timestamped links. Header tools include Export recording, Undock, Fullscreen, and Terminal settings. Settings adjust font, fit, theme, idle pauses, and optional terminal features. Drag/resize an undocked player, or use focused handles with arrow keys; Dock returns it.

termbacktime play demo.tbt --speed 2 --idle-limit 2s
termbacktime play github-user/recording-id

CLI playback accepts local recordings, supported journals, and share links. --no-interactive disables keyboard controls. q, Esc, or Ctrl+C exits.

Playback shortcuts

On the homepage, shortcuts apply while focus is inside the demo.

Remember playback position

History is opt-in. CLI and browser settings are independent:

termbacktime history enable
termbacktime play demo.tbt --no-history
termbacktime history disable
termbacktime history clear

Use manager H, or browser Remember playback position / Clear playback history. Reopening offers Resume / Start over; explicit URL timestamps take precedence. Disabling keeps positions; clearing removes them without changing the setting.

History stores up to 100 positions locally, without recording content, links, or keys. It clears completed positions and excludes live sessions, demos, embeds, unfinished journals, and noninteractive CLI playback. Encrypted recordings qualify after unlocking.

Choose an export

Use Export recording in the browser or offline player:

termbacktime export demo.tbt --format txt --output transcript.txt
termbacktime export demo.tbt --format md --output transcript.md

The CLI exports text and Markdown transcripts. Runnable scripts are generated in the website and offline players. Offline HTML includes playback and export tools; ordinary HTML contains readable content. Protected HTML requires a passphrase of at least 12 UTF-8 bytes. GIF/WebM exports support up to 60 seconds after timing adjustments, 1280 × 720, and 32 MiB, with progress and cancellation.

Unpack inspects events and downloads expanded JSON; JSON inspection output cannot be reopened as a recording.

Review a runnable script

Choose Runnable script to select a target (macos, debian, fedora, arch, or alpine) and interpreter (Bash, zsh, or fish). Complete successful captured commands start selected; inferred, failed, and incomplete commands start unselected. You can include any command. Command notices and translation suggestions are advisory and do not block the preview or export. Use a literal prompt prefix for custom extraction or add missing commands manually.

Edit commands and compare each proposed translation with its original. Accept translations if desired, supply required variables, and review the script preview before enabling Download script. Changing the target preserves command selections and manual edits, updates accepted translations, and clears only the final review checkbox. Use a workspace is off by default: commands start in the directory where you launch the script, with no automatic directory changes. Enable it to map recorded directories under the source workspace to required TBT_WORKDIR; other paths then require explicit mappings. Credential literals should become required variables with no secret defaults. Additional prerequisites are included as comments. Edits stay in memory until Save plan; Import plan restores a saved tbt-script-plan-v1 JSON plan in the website or an offline player.

Download the script and run it with the selected interpreter, for example:

bash setup.sh
# If Use a workspace is enabled:
TBT_WORKDIR=/path/to/workspace bash setup.sh

For zsh or fish, run the downloaded .zsh or .fish file with that interpreter. Scripts preserve command order and shell state; playback speed, pauses, and loops do not affect them. They stop on failure by default, with an editable continue option. Export never executes scripts, and browser exports are not syntax checked.

Confirm before running is on by default. Generated scripts ask Run this script? [y/N] in the terminal before setup or commands run. Enter y or yes to continue; other responses, empty input, or no available terminal cancel execution. Turn the toggle off to omit the prompt for unattended runs. Saved plans retain this setting.

Automatic package mapping supports an explicit allowlist; unknown packages, pinned versions, custom repositories, unsupported flags, and complex syntax are exported as written unless you edit them. Linux installations require root or sudo, Homebrew runs without added sudo, and Arch requires an already updated system. This workflow runs locally in the website and offline players, including protected recordings after unlocking. Plans and scripts retain the 64 MiB limit. Arbitrary shell grammar, edited files, and the full environment cannot be reconstructed automatically; repeat-run idempotence is not guaranteed.

Embedding on third-party websites

Embed a recording

Open an unencrypted share, choose a timestamp, and select Copy iframe embed. Paste into a page allowing HTML:

<iframe
    src="https://termbackti.me/embed/GITHUB_USER/RECORDING_ID?start=12.5&theme=dark"
    title="Terminal recording"
    width="800"
    height="450"
    style="width:100%;border:0"
    loading="lazy"
    allowfullscreen
></iframe>

Repository URLs use /embed/GITHUB_USER/RECORDING_ID; Gists use /embed/GIST_ID. Public repository recordings and public or secret Gists work. Encrypted recordings do not. Embedding a secret Gist exposes its link/content to visitors.

Embeds start paused without history and link to hosted playback at the current time. Adjust iframe dimensions; query options configure the interface:

Export formats: tbt,txt,md,script,snapshot,html,protected,gif,webm. For example, ?exports=txt,md&font=18&fit=0 enables transcripts with fixed-size text. These switches do not restrict access to recording content.

Normal playback pages block framing. If sandboxing, allow scripts and same-origin execution, downloads for exports, and popups for hosted links. allowfullscreen enables fullscreen. GitHub must still serve the publication; fetch errors appear inside the player.

Share live

termbacktime live
termbacktime live --record --ttl 2h --title "Build walkthrough"
termbacktime live --output demo.tbt --no-dashboard -- npm test

Send the complete viewer link for an encrypted, read-only terminal view. Keep the private host link to yourself: it manages viewer counts, admission, pausing, and ending sharing. Pause/end leaves your shell and local recording running.

Live sharing saves only when --record or --output is supplied. Sessions default to eight hours within deployment limits and support 100 viewers. Viewers see the current screen and rewind five minutes received since joining.

Interactive terminals open the dashboard automatically. Ctrl+] opens link controls; Esc returns and ] forwards a literal control key. --no-dashboard or redirected output uses a plain view. Status and connection diagnostics stay outside captured output.

Files and recovery

Data defaults to ~/termbacktime: recordings/ holds sessions, library/ indexes them, shares/ keeps private receipts, and termbacktime.json holds configuration.

--data-dir or TERMBACKTIME_DATA_DIR selects another root; --config independently selects configuration. Custom output paths create parents without overwriting files.

termbacktime recover /path/to/session.partial --output recovered.tbt
termbacktime record --sync-interval 1s

Recovery preserves the source and refuses active journals. Browsers require finalized .tbt files; the CLI can play complete supported journal events. Capture syncs every event by default; a one-second interval risks losing that much output after a machine crash.

Manager d requires typing delete. Local deletion includes imported files at their original location. Gist deletion removes the entire Gist; repository deletion creates a commit, retaining earlier copies in Git history. Local and remote deletion are independent; receipts remain.

Troubleshooting

termbacktime doctor --json
termbacktime doctor --live --relay-only
termbacktime completion bash

Diagnostics check paths/permissions; --live tests delivery in a temporary room; --relay-only tests TURN. --endpoint or SITE_URL selects a website.

Use termbacktime COMMAND --help. Completion supports bash, zsh, fish, and PowerShell. Report issues without credentials, private links, or sensitive output.

Platforms and uninstalling

Binaries support macOS Intel/Apple Silicon, Linux amd64/386/arm64/ARMv6/ARMv7, and FreeBSD amd64/386. Use WSL on Windows.

Remove the executable to uninstall. Recordings/configuration remain. Legacy configuration migrates only when no destination exists; an explicit --config keeps using that file.

Storage and compatibility

termbacktime storage usage --json
termbacktime storage clean --kind recordings --older-than 30d --min-size 10MiB
termbacktime storage clean --kind exports --apply
termbacktime storage clean --kind queue --apply --yes --json
termbacktime storage pin demo.tbt
termbacktime storage unpin demo.tbt

Cleanup previews first. Filters combine with AND; age uses modification time. --apply requires typed confirmation, or --apply --yes for scripts. Pins, imports, unfinished journals, unresolved jobs, configuration, history, and receipts are protected. In manager storage, Tab chooses kind, a/m edit age/size, Space selects, A selects all filtered items, and Enter reviews deletion.

Local capture, recovery, inspection, and playback support 1 GiB expanded data. Uploads, scans, redaction, transcripts, and offline exports retain 64 MiB limits. Only .tbt v1 recordings and supported journals are accepted. Old files remain untouched; there is no automatic conversion.

GitHub Actions

The Action records commands and uploads cleaned failure artifacts. In this checkout:

name: Tests
on: [push, pull_request]
jobs:
    test:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v7.0.1
            - uses: ./termbacktime
              with:
                  command: go test ./...
                  working-directory: termbacktime

Use ./ in the extracted CLI repository or termbacktime/termbacktime@TAG_OR_SHA for a published revision. Prepare dependencies first.

Inputs are required command; shell (bash), working-directory (.), artifact-name (terminal-failure), and retention-days (7). Outputs are exit-code, artifact-id, and artifact-url. Use Linux/macOS runners; the Action installs Go.

Success uploads nothing. Failure preserves the command's status and uploads terminal-recording.tbt after detected-secret redaction and rescanning. Download from the workflow run, then use termbacktime play terminal-recording.tbt or browser playback. Preparation failures publish only diagnostic.txt. Review recordings before sharing; automatic detection cannot identify every secret.