---
title: "CLI — Retrace"
description: "Official Retrace CLI installation and automation guide for Homebrew, direct binaries, authentication, traces, forks, and CI evaluation gates."
canonical: "https://retraceai.tech/developers/cli"
last-updated: 2026-08-26
format: text/markdown
---

# CLI

Use the official Retrace CLI to authenticate, inspect traces, create and replay forks, and run evaluation gates from macOS, Linux, Windows, or CI.

## What it does

- **Published on Homebrew** — Install the official retraceai-tech/tap/retrace-cli cask on macOS, Linux, or WSL.
- **Signed checksums** — Versioned binaries and SHA-256 checksum files are published for every supported platform on the Retrace CDN.
- **Browser device login** — retrace auth login opens a short-lived device flow instead of asking you to paste credentials into shell history.
- **CI exit codes** — retrace eval gate exits non-zero when behavior misses the configured threshold or regresses.

## Examples

Install the official Homebrew cask.

```terminal
brew install --cask retraceai-tech/tap/retrace-cli
```

Authenticate and inspect recent runs.

```terminal
retrace auth login
retrace traces list
retrace --help
```

Fail a build when agent behavior regresses.

```ci
retrace eval gate \
  --evaluation "$EVALUATION_ID" \
  --trace "$TRACE_ID" \
  --threshold 0.8
```


## Official distribution

- `Homebrew: https://github.com/Retraceai-tech/homebrew-tap`
- `Install script: https://retraceai.tech/install.sh`
- `Latest version: https://cdn.retraceai.tech/cli/latest/VERSION`

## Related

- HTML page: https://retraceai.tech/developers/cli
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md