Getting started¶

This tutorial gets you from a fresh install to a useful carrier workflow.

Before you start¶

You need:

• a terminal on Linux, macOS, or Windows PowerShell
• either the installer script or Go installed locally
• write access to your user config and data directories

Run this after install:

carrier doctor

doctor checks config, data directories, notification tooling, shell support, and log storage. Fix anything marked error before using carrier in scripts.

What carrier is¶

carrier records command executions on your machine. It captures:

• command and arguments
• working directory
• start and finish time
• duration
• exit code
• stdout and stderr logs
• Git root, branch, commit, and dirty state

It is most useful for test runs, builds, migrations, deploy commands, long Docker tasks, and debugging sessions.

What carrier is not¶

carrier is not a hosted service, terminal replacement, shell history replacement, or CI system.

Install carrier¶

curl -fsSL https://raw.githubusercontent.com/atbuy/carrier/main/install.sh | sh

irm https://raw.githubusercontent.com/atbuy/carrier/main/install.ps1 | iex

Specific versions and Go installs are covered in Installation.

Verify:

carrier version
carrier doctor

Add a short alias¶

Most examples use:

alias c='carrier'

Add that to ~/.zshrc or ~/.bashrc, then reload your shell:

source ~/.zshrc

Use source ~/.bashrc if you use bash.

First five minutes checklist¶

1. Install carrier.
2. Run carrier doctor.
3. Record one command with carrier run <command...>.
4. Inspect it with carrier last and carrier show <run-id>.
5. Add alias c='carrier' once you are comfortable with the command.

The run ID appears in last, history, failed, running, and most JSON output. Use that ID with show, tail, export, label, rerun, and clean previews.

Record your first command¶

Run a simple command:

c run echo "hello from carrier"

You should see normal terminal output. carrier records metadata and saves logs.

Show latest run:

c last

Inspect full details:

c show 1

If your first run ID is not 1, use ID shown by last.

Record a command that fails¶

Run:

c run bash -c 'echo stdout; echo stderr >&2; exit 7'
echo $?

The final echo $? should print 7. carrier run preserves child exit code.

List failed runs:

c failed

Search output¶

Search command text, cwd, stdout, stderr, and terminal logs:

c search "stderr"

Export a run¶

Export run details as Markdown:

c export 1 > run-1.md

This is useful when sharing a failure with teammates or adding context to an issue.

Rerun a command¶

Run again from original working directory:

c rerun 1

This creates a new run record. It does not overwrite the old run.

Clean old runs safely¶

Preview deletion:

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

Actually delete:

c clean --older-than 30d --yes

Browse runs interactively¶

Use the full-screen browser when you want to scan recent runs and preview output without remembering IDs:

c tui

Inside the browser you can move through runs, filter by command/status/cwd/label, label important runs, delete old runs, and choose a run to rerun. Reruns start after the browser exits so the command runs in your normal terminal.

Shell sessions (alpha)¶

carrier shell starts a tracked shell where every command is recorded automatically and grouped under a session. Label it so you can find it later:

c shell 'my-debug-session'

Inside the shell, run commands normally. Exit when done. Then review:

c history --session my-debug-session

Use carrier attach to re-open a session from a different terminal:

c attach my-debug-session

Shell mode is alpha and best-effort for zsh/bash. See Shell mode for details.

Next steps¶

• Read First run tutorial for a realistic build/test example.
• Read Commands for full command coverage.
• Read Shell mode to learn about sessions and carrier attach.
• Read Configuration reference before changing storage, redaction, or notifications.