The shortest path from `roar` installed to a real DAG you can look at.

## Install

```bash
uv tool install roar-cli    # recommended
pipx install roar-cli       # alternative
```

Requires Python 3.10+. Linux (x86_64 / aarch64) and macOS (arm64 / x86_64) are supported; Windows isn't yet. The default tracer works everywhere; eBPF-based tracing additionally requires Linux ≥ 5.8 with `CAP_BPF`. For the full platform matrix, tracer-backend prerequisites, macOS SIP notes, and sdist build steps, see [Installation](/docs/installation).

## Initialize roar in a project

```bash
cd ~/your-project
roar init
```

This creates a `.roar/` directory next to your `.git/`. One-time per repo.

## Run commands as usual — just prefix with `roar run`

```bash
roar run python preprocess.py --input data.csv --output features.parquet
roar run python train.py --data features.parquet --output model.pt
roar run python evaluate.py --model model.pt --output metrics.json
```

Nothing about your scripts changes. `roar` records the command, what it read, what it wrote, the git commit, your environment, exit status, and timing.

## Inspect what you just built

```bash
roar status      # active session, latest job, tracked artifacts
roar dag         # the inferred pipeline
roar show model.pt   # full lineage of one artifact — including how to reproduce it
```

You now have:

- A recorded history of every run
- A DAG inferred from the actual file flow — not declared
- A way to answer *"where did this artifact come from?"* by hash

…with zero pipeline configuration.

## Publish to GLaaS

Everything so far is local. To make an artifact's lineage globally lookup-able by hash, register it with **GLaaS** (Global Lineage-as-a-Service):

```bash
roar register model.pt
```

This publishes the artifact's lineage — the chain of jobs and inputs that produced it — to GLaaS. Anyone with the resulting hash can then look it up at [glaas.ai](https://glaas.ai), or reproduce it (next section).

A new repo defaults to the **anonymous** scope so you can try `roar register` without an account; each register prompts to confirm the public publication (skip with `roar register -y`). To publish privately or under a project, run `roar login` and `roar scope use <private | public | <owner>/<project>>`. See [Scopes](/docs/scopes) for the full picture.

## Reproduce someone else's artifact

Given a hash that's registered to GLaaS, anyone can recreate the artifact:

```bash
roar reproduce <artifact-hash>
```

`roar` walks the lineage backward, clones the right code, sets up the environment, and re-runs the chain.

## Where to next

- [Why roar + GLaaS?](/docs/why-roar-glaas) — the design philosophy behind implicit observation
- [Core Concepts](/docs/core-concepts) — jobs, artifacts, sessions, DAGs
- [roar Guide](/docs/roar-guide) — full CLI reference and registration setup
- [Common Use Cases](/docs/use-cases) — recipes for real workflows