Commands¶

This page documents every carrier command and the flags users usually need.

Human-readable output is colorized on TTYs. Set NO_COLOR=1 to disable colors or CARRIER_COLOR=always to force colors in non-TTY output.

Global flags¶

These flags apply to any command that runs or inspects commands.

carrier run --timeout 30s go test ./...
carrier run go test --timeout 30s

run¶

Run one command and record it:

carrier run go test ./...
carrier run docker compose build
carrier run bash -c 'make clean && make'

Useful flags:

Behavior:

• streams stdout and stderr live
• stores stdout and stderr separately
• records metadata, Git context, and environment when enabled
• preserves child exit code
• redacts persisted logs by default
• caps persisted logs by storage.max_output_mb

last¶

Show latest run:

carrier last        # show latest run
carrier last 5      # show latest 5 runs
carrier last 5 --json   # JSON array of latest 5

tui¶

Browse recorded runs in an interactive, full-screen viewer:

carrier tui
carrier ui   # alias

The screen is split into a run list on the left and a live output preview on the right. Move through the list to preview each run's details and captured output. You can rerun, label, or delete runs without leaving the browser.

Rerun launches after the browser exits, so the command runs in your normal terminal (not nested inside the viewer).

The preview shows stdout/stderr for carrier run commands. Shell-session recordings rely on terminal control sequences and can't render faithfully in the preview, so the browser points you to carrier show <id> or carrier tail <id> to replay them in a real terminal instead.

Keys¶

While filtering, enter applies the filter and esc clears it. Deleting a run also removes its log files and prunes any environment snapshot it no longer shares.

history¶

List recorded runs oldest-first:

carrier history
carrier history --limit 50

Filter history:

carrier history --status failed
carrier history --since 24h
carrier history --cwd api
carrier history --branch main
carrier history --command 'go test'
carrier history --label deploy
carrier history --json

Session grouping¶

List rows show a colored status glyph (✓ success, ✗ failed, ● running, ⊘ killed), a relative timestamp (2m ago), the duration, the command, and the working directory with your home directory collapsed to ~. Absolute timestamps are shown in carrier show.

When runs belong to shell sessions, history displays them as a tree with session headers:

   5  ┬──  active    12m ago   backend-debug
   3  ├──  ✗ failed   12m ago   1.2s   make test     ~/api
   2  └──  ✓ success  12m ago   0.4s   go vet ./...   ~/api
   1       ✗ failed   15m ago   2.1s   make lint      ~/api

Filter to a specific session by ID or label:

carrier history --session 5
carrier history --session backend-debug

Show only session headers, no individual runs:

carrier history --sessions-only

Use with fzf:

carrier history | fzf | awk '{print $1}' | xargs carrier rerun

show¶

Show metadata and captured output:

carrier show 42
carrier show 42 --json

Output controls:

carrier show 42 --lines 100
carrier show 42 --stdout
carrier show 42 --stderr
carrier show 42 --env

--stdout and --stderr print only that stream, with no metadata header. --env prints captured environment variables when storage.capture_env = true.

For runs captured in shell mode where a TUI application used the alternate screen (neovim, lazygit, noteui, etc.), the output section shows (TUI session — terminal output suppressed) instead of replaying the log. Run metadata is still fully recorded.

tail¶

Stream captured output:

carrier tail 42
carrier tail 42 --stream stdout
carrier tail 42 --stream stderr
carrier tail 42 --stream terminal

For carrier run, the default --stream both prefixes lines:

stdout | ...
stderr | ...

For carrier shell, terminal output is a single stream. Use --stream terminal or the default both.

failed¶

List failed runs:

carrier failed

running¶

List currently running commands:

carrier running
carrier running --json

Use tail from another terminal to watch a running command:

carrier tail 42

search¶

Search commands, cwd, and output:

carrier search "connection refused"
carrier search --since 24h "timeout"
carrier search --since 7d --status failed "OOM"
carrier search --status running "migration"
carrier search --limit 25 "permission denied"
carrier search --json "timeout"

Search uses SQLite FTS over command text, working directory, and stored output snippets. A LIKE fallback catches command/cwd substring matches that token search may miss.

stats¶

Show run totals, runs per active day, failure rate, average duration, and slowest commands:

carrier stats
carrier stats --slowest 10
carrier stats -c 'go test'          # filter to commands matching substring
carrier stats --command 'make'
carrier stats --json

diff¶

Diff the captured output of two runs:

carrier diff 41 42
carrier diff --stream stderr 41 42
carrier diff --raw 41 42

By default, ANSI escape sequences are stripped before diffing so the output shows readable text. Use --raw to diff the log files directly.

--stream selects which output stream to compare:

Colors follow NO_COLOR / CARRIER_COLOR / --color config.

export¶

Export a run as Markdown by default:

carrier export 42 > run-42.md

Other formats:

carrier export 42 --format json > run-42.json
carrier export --format csv > runs.csv
carrier export 42 --format csv > run-42.csv

rerun¶

Run original argv from original cwd:

carrier rerun 42
carrier -n rerun 42

Edit the argv JSON before rerunning:

carrier rerun 42 --edit

rerun creates a new run. It never overwrites the old record.

Useful flags:

label¶

Attach a short label to a run:

carrier label 42 prod deploy
carrier history --label prod

Clear a label by omitting text:

carrier label 42

When a run belongs to a shell session, label also updates the session label. This keeps the history tree consistent: runs and their session share the same label.

watch¶

Re-run a command when files in the current directory change:

carrier watch go test ./...
carrier watch --pattern '*.go' go test ./...
carrier watch --debounce 500ms go test ./...

Useful flags:

watch recursively watches the current directory and skips .git, node_modules, and vendor. Before each re-run, it prints carrier: changed: <file> (suppressed by --quiet). Ctrl-C correctly stops both the watcher and any running child process. --help is supported.

shell¶

Start an alpha tracked shell session:

carrier shell

Attach a label at start with --label or a positional argument:

carrier shell --label backend-debug
carrier shell 'backend-debug'

The label appears in carrier history session headers and in carrier session list.

Use carrier run when precise stdout/stderr capture matters. See Shell mode.

attach¶

Attach to an existing shell session by session ID or label:

carrier attach 5
carrier attach backend-debug

attach re-opens the session, starts a new PTY shell that records commands into it, then closes the session when you exit. Runs recorded during the attached shell appear grouped under the same session in carrier history.

This is useful when you need to return to a named session after disconnecting, or when you want to continue work in a labeled debugging context from a different terminal.

session¶

Manage shell session labels and history.

session list¶

List sessions newest-first:

carrier session list
carrier session list --limit 20

Output includes session ID, start time, label, and duration (or active for open sessions).

session label¶

Set or clear a session label:

carrier session label 3 backend-debug
carrier session label 3               # clear label

When inside a tracked shell (carrier shell or carrier attach), the session ID is available as $CARRIER_SESSION_ID. Omit the ID argument to target the current session:

carrier session label backend-debug
carrier session label               # clear current session label

clean¶

Preview deletion:

carrier clean --older-than 30d --dry-run
carrier clean --older-than 30d -d

Delete old records and logs:

carrier clean --older-than 30d --yes
carrier clean --older-than 30d -y

Keep only recent records:

carrier clean --keep-last 500 --dry-run
carrier clean --keep-last 500 --yes

Deletion requires --yes. Use --dry-run first.

doctor¶

Check local setup:

carrier doctor

Shows version, config path, storage paths, migration version, data size, redaction status, stale running runs, shell support, notification tool availability, and terminal status.

config¶

Inspect and create config:

carrier config path
carrier config show
carrier config check
carrier config init
carrier config init --force

completion¶

Generate a shell completion script:

# Bash — write once, restart shell
carrier completion bash > /etc/bash_completion.d/carrier

# Bash — per-session (add to ~/.bashrc for persistence)
source <(carrier completion bash)

# Zsh
carrier completion zsh > "${fpath[1]}/_carrier"

# Fish
carrier completion fish > ~/.config/fish/completions/carrier.fish

# PowerShell (add to $PROFILE)
carrier completion powershell | Out-String | Invoke-Expression

version¶

carrier version