Skip to content

Getting started

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

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.

Note

Everything is local. Metadata is stored in SQLite, and output logs are stored as files under your local data directory.

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:

Verify install
carrier version
carrier doctor

Add a short alias

Most examples use:

Shell alias
alias c='carrier'

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

Reload zsh config
source ~/.zshrc

Use source ~/.bashrc if you use bash.

Record your first command

Run a simple command:

Record a simple command
c run echo "hello from carrier"

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

Show latest run:

Show latest run
c last

Inspect full details:

Show full details
c show 1

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

Record a command that fails

Run:

Record a failing command
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:

List failed runs
c failed

Search output

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

Search output
c search "stderr"

Export a run

Export run details as Markdown:

Export 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:

Rerun original argv
c rerun 1

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

Clean old runs safely

Preview deletion:

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

Actually delete:

Delete old records and logs
c clean --older-than 30d --yes

Next steps