# Getting started

> Get oriented, and find your way around the docs.

::div{class="flex items-start gap-6 grid grid-cols-3"}
:img{src="/treqs-mark.svg" alt="TReqs" :zoom="false" class="mt-2 rounded-4xl min-w-24 object-contain"}

::div{class="col-span-2"}
**TReqs** is where machine-learning training work gets planned, reviewed, and run. You describe a training run as a **training request** — code at a specific commit, a workflow file, and a compute target — put it up for review the way you would a pull request, and queue it once it's approved.
::
::

## Sign in

TReqs uses your GitHub account, so there's no separate password to create. Go to the [sign-in page](/login) to get started.

Everything in TReqs belongs to an organization. [Create one](/docs/organizations) if you're the first person here, or accept an invitation if a colleague has already added you.

## Built for agents

All of these docs describe what you can do in the TReqs Dashboard, but almost all of that can also be done with the [TReqs CLI](https://github.com/treqs/treqs-cli) ([read docs](/docs/cli)) — creating projects, writing and opening training requests, configuring compute targets and their secrets, queueing runs, reading logs. No operation exists only as a button, so a coding agent can drive the whole loop rather than stopping at the parts that were automatable.

Three things make it work unattended:

- **`--json` on any command**, for machine-readable output. It goes before the subcommand: `treqs --json whoami`.
- **Token auth with no browser.** `TREQS_API_TOKEN` takes precedence over a stored login, so an ephemeral environment needs no device flow.
- **Exit codes that mean something.** `treqs jobs wait` exits non-zero unless the run reached **Completed**, so a run that fails fails the script around it.

These docs are agent-readable too. Append `.md` to any page for its markdown source, or start from [llms.txt](/llms.txt) for the index and [llms-full.txt](/llms-full.txt) for the whole corpus.

## Where to go next

### Understand the pieces

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-shapes" title="roar, GLaaS, and TReqs" description="Three tools, one lineage story, and which one does what." to="/docs/roar-glaas-treqs"}
:u-page-card{icon="i-lucide-folder-git-2" title="Projects" description="Connect a GitHub repository and give training work a home." to="/docs/projects"}
::

### Set up your organization

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-building-2" title="Organizations" description="Create one, or join one you've been invited to." to="/docs/organizations"}
:u-page-card{icon="i-lucide-server" title="Compute targets" description="Where training actually runs, plus the secrets your workflows need." to="/docs/compute-targets"}
:u-page-card{icon="i-lucide-users" title="Members and roles" description="Roles, seats, and who is allowed to change what." to="/docs/members-and-roles"}
:u-page-card{icon="i-lucide-bell" title="Notifications" description="Slack, in-app, and email." to="/docs/notifications"}
::

### Run something

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-file-code-2" title="Workflows" description="The workflow file that defines the stages of a run." to="/docs/workflows"}
:u-page-card{icon="i-lucide-git-pull-request" title="Training requests" description="The review unit: what goes in one, and how approval works." to="/docs/training-requests"}
:u-page-card{icon="i-lucide-play" title="Training runs" description="Queueing, watching progress, reading logs, publishing lineage." to="/docs/training-runs"}
:u-page-card{icon="i-lucide-share-2" title="Publishing to GLaaS" description="Visibility modes, and republishing lineage that didn't land." to="/docs/publishing-to-glaas"}
::

### Reference

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-chart-line" title="Insights" description="Activity and cost across an organization or project." to="/docs/insights"}
:u-page-card{icon="i-lucide-terminal" title="CLI" description="Do all of the above from a terminal." to="/docs/cli"}
::


---

# roar, GLaaS, and TReqs

> Three tools, one lineage story — and which one you reach for when.

## Code + Compute + Conversation = Full Context

TReqs is one of three tools that share a single idea: the history of a model should be a fact you can look up, not something you reconstruct from memory. Each covers a different part of that.

[**roar**](https://github.com/treqs/roar) is a command-line tool that watches your commands as they run. Prefix a command with `roar run` and it records what was read, what was written, the git commit, the environment, exit status, and timing — without you declaring a pipeline or writing extra configuration. The result is a DAG inferred from what actually happened on disk.

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-book-open" title="roar guide" to="https://glaas.ai/docs/roar-guide" target="_blank"}
::

[**GLaaS**](https://glaas.ai) (Global Lineage-as-a-Service) is the registry roar publishes to. It makes an artifact's lineage lookup-able by its content hash, from anywhere. Given a model file, GLaaS answers what produced it, from which inputs, at which commit.

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-book-marked" title="GLaaS docs" to="https://glaas.ai/docs" target="_blank"}
::

**TReqs** is where the work gets planned, reviewed, and executed. A training request describes an intended run — code at a commit, a workflow, a compute target — and goes through review before anyone spends GPU hours on it. When it runs, TReqs executes it on your compute and publishes the resulting lineage to GLaaS.

## How they fit together

Read left to right, they cover intent, execution, and record:

- **TReqs** holds the *intent*: what we plan to train, why, who approved it.
- **roar** observes the *execution*: what the run actually touched.
- **GLaaS** keeps the *record*: a permanent, searchable lineage graph.

A training run in TReqs uses all three. TReqs clones your repo at the pinned commit onto a compute target, runs the stages in your workflow file, and — when roar is installed on that target — captures lineage as those stages execute. At the end, the run publishes to GLaaS according to the visibility you chose. See [Training runs](/docs/training-runs) for the publishing options.

## Which do I need?

You can use them independently.

- **roar alone** is useful on a laptop. It answers "where did this file come from?" locally, with no account and no server.
- **roar + GLaaS** makes those answers shared and permanent, so a colleague can reproduce your artifact from its hash.
- **TReqs** adds the parts a team needs: shared compute, a review step before expensive runs, and a record of who approved what.

If you only want lineage, you do not need TReqs. If you want a team to agree on a training run before it happens, and to run it on shared infrastructure, that's what TReqs is for.

## Going the other direction

The flow also runs backwards. If you already have a DAG in GLaaS — something you ran locally with roar and registered — you can turn it into a training request rather than writing one from scratch, starting from **Run on TReqs** in GLaaS. TReqs reads the session's lineage and pre-fills the code, commit, and stages it observed.

## Next

- [Projects](/docs/projects) — connect a repository so TReqs has code to run.
- [Compute targets](/docs/compute-targets) — give it somewhere to run.


---

# Organizations

> Create an organization, or accept an invitation to join one.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-building-2" class="size-16 text-primary"}
::

An **organization** owns projects, compute targets, and members. Every piece of work in TReqs belongs to one, so it's the first thing to set up. Most teams want exactly one.
::

## Create an organization

1. From your home page, open the organization switcher and choose **New organization**.
2. Pick a handle. It appears in every URL beneath it — `/<org>/<project>` — so choose something short and stable.
3. You become the organization's **owner**.

Once it exists, add the people you work with. See [Members and roles](/docs/members-and-roles) for what each role can do and how writer and reader seats differ.

## Accept an invitation

If someone adds you to their organization first, you'll get an invitation by email.

1. Open the invitation link from your email.
2. Review the organization, the role, and the seat kind you're being offered.
3. Choose **Join organization**.

Invitations expire. If yours has, ask an admin of that organization to send a new one. Accepting one never affects any other organization you belong to — you can be a member of several.


---

# Projects

> Connect a repository and give training work somewhere to live.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-folder-dot" class="size-16 text-primary"}
::

A **project** in TReqs points to code in a repository so that training work can be planned and orchestrated. Training requests, runs, and workflows all belong to a project. Projects belong to an [organization](/docs/organizations), and appear in URLs as `/<org>/<project>` (just like GitHub).
::

Compute is *not* per-project — compute targets are shared across an organization. See [Compute targets](/docs/compute-targets).

## Create a project

From an organization's **Projects** page, choose **New project**. You'll need:

- A **name**, which becomes the project slug in URLs.
- A **visibility** — `public` or `private`. Private projects are visible only to members of the owning organization.
- A **repository** to connect, though you can add that afterwards.

```bash [TReqs CLI]
treqs projects create --name my-project
treqs project use my-project     # bind the current repo
```

`treqs project use` writes the binding into the repo, so subsequent `treqs tr` commands know which project they belong to without you naming it every time.

## Connect a repository

Under **Configure → Code**, connect the GitHub repository the project's training runs will clone. There are two access modes.

### GitHub App (private or public repositories)

Install the TReqs GitHub App on the account or organization that owns the repository, then pick the repository from the list. This is the mode you want for private repositories — the App's installation token is what lets TReqs clone them.

You control which repositories the App can see when you install it, and you can change that later from GitHub's own settings. TReqs only requests read access to repository contents.

### Public URL

For a public repository you can skip the App and point the project at the repository URL directly. Nothing is installed and no token is stored. TReqs clones it the way any anonymous client would.

This is the quicker path for open-source work, but it only works while the repository stays public. If it's made private later, runs will start failing to clone and you'll need to switch to the GitHub App mode.


---

# Members and roles

> Adding people to an organization — what each role can do, and how writer and reader seats differ.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-users" class="size-16 text-primary"}
::

An organization's members are managed under **Configure → Members**. Every member has two independent settings: a **role**, which says what they're allowed to administer, and a **seat kind**, which says whether they can change anything at all.
::

## Roles

| Role | Can do |
| --- | --- |
| **Owner** | Everything, including owner-only settings and billing. |
| **Admin** | Manage members, projects, and compute. Cannot change owner-only settings. |
| **Member** | Work in the organization — create projects, write training requests, review, queue runs. |

The **owner** is the person who created the organization. Some settings are deliberately owner-only rather than admin-accessible — notably the permissions configuration that decides which admins may set training-request controls, described in [Training requests](/docs/training-requests). The point is that admins can't quietly widen their own authority.

**Member** is the right role for most people. Give someone **Admin** when they need to add other people or manage compute, not as a general seniority marker.

## Seats

Seat kind is separate from role, and it's the one people find surprising:

| Seat | Means |
| --- | --- |
| **Writer** | Can create and change things — projects, training requests, reviews, runs. |
| **Reader** | Read-only. Can see the organization's work but not modify it. |

A reader seat is read-only *regardless of role*. Reader controls are disabled throughout the dashboard rather than hidden, so it's clear you're looking at something you can't change rather than something that isn't there.

Reader seats exist for people who need visibility without participation — a manager tracking progress, someone in a neighbouring team, an auditor.

Writer and reader seats are counted and billed differently. For what each plan includes, see [treqs.ai/pricing](https://treqs.ai/pricing) — plans and prices live there rather than here so they stay current.

## Inviting someone

From **Configure → Members**, choose **Invite**, and supply:

- Their **email address**.
- A **role** — Admin or Member. You can't invite someone directly as owner.
- A **seat kind** — Writer or Reader.

Because adding a writer seat can change what the organization is billed, the dashboard shows the billing impact before the invitation is sent, and asks you to confirm it when the change is significant. Nothing is charged silently.

## The invitation lifecycle

An invitation is in one of four states:

| State | Meaning |
| --- | --- |
| **Pending** | Sent, not yet accepted. |
| **Accepted** | They joined. They're now a member. |
| **Expired** | It sat too long. Send a new one. |
| **Revoked** | An admin withdrew it before it was accepted. |

The recipient sees it under **Invitations**, showing the organization, role, seat kind, and expiry, and joins explicitly — nothing is auto-accepted by opening a link.

You can revoke a pending invitation at any time. Once it's been accepted, revoking is no longer the tool — remove the member instead.


---

# Compute targets

> Where training runs execute — dedicated machines, on-demand cloud instances, and the secrets they need.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-cpu" class="size-16 text-primary"}
::

A **compute target** is somewhere a training run can execute. Targets are configured at the organization level and shared across all of that organization's projects — you set up a GPU box or a cloud provider once, and every project can queue work onto it.
::

## Dedicated

A machine you already have — a workstation under a desk, a rack server, a long-lived cloud VM. You install the TReqs agent on it and register it against the target using a registration code:

```bash [TReqs CLI]
treqs compute targets create --name gpu-box
treqs compute targets registration-code create --target gpu-box
```

The agent polls TReqs for work. A dedicated target shows as **online** or **offline** depending on whether its agent has checked in recently. Nothing is provisioned or billed by TReqs — you own the machine and it's available whenever it's running.

## On-demand

TReqs launches an instance from a cloud provider when a run needs one, and shuts it down afterwards. Nothing runs — and nothing costs — between jobs.

```bash [TReqs CLI]
treqs compute targets create --kind on-demand --name burst \
    --type runpod --instance-type cpu3c
```

On-demand targets take an instance type and a region (or `any`). Useful extras:

- `--auto-shutdown` with `--idle-timeout` to stop paying for an idle box.
- `--install-roar` to install roar as part of the managed bootstrap, so runs on that target capture lineage.
- `--userdata-script` for anything else that needs to happen at startup.

You can watch what a target has launched:

```bash [TReqs CLI]
treqs compute targets instances gpu-burst
```

## Configuration

### Providers

On-demand targets currently support **AWS**, **GCP**, **Azure**, **RunPod**, and **Lambda**.

AWS takes the most configuration, because TReqs launches into *your* account and VPC:

- `--ami-id` — required for AWS launches. Omit it in an interactive session with a concrete region and you can pick from a live list.
- `--subnet-id` — repeatable. The first is primary; the rest are fallbacks tried when an availability zone reports a capacity error.
- `--security-group-id` — repeatable, optional.
- `--ssh-key-name` — an EC2 key pair to attach, if you want to be able to log in.

### Provider credentials

Before TReqs can launch anything, it needs permission in your cloud account. Add credentials under **Configure → Compute → Credentials**. Each provider is connected the way that provider prefers, rather than by pasting long-lived keys:

- **AWS** — you create a role that trusts the TReqs compute broker and grant it the permissions to launch instances.
- **GCP** — you grant the TReqs broker service account the ability to impersonate a service account in your project.
- **Azure** — you consent to the multi-tenant TReqs application in your tenant and give it resource-group-scoped roles.

The dashboard shows the exact principal to trust for each, and runs a connection test afterwards. Credentials report as **valid**, **invalid**, or **unknown**; an invalid credential means launches on that provider will fail, so fix it before queueing work.

### Secrets

Runs usually need credentials of their own — a Weights & Biases key, a Hugging Face token, an API key for something your training script calls. These are **compute target secrets**: set on a target, injected into the environment of runs that execute there.

```bash [TReqs CLI]
treqs compute secrets set --target gpu-box WANDB_API_KEY=abc123
treqs compute secrets set --target gpu-box HF_TOKEN=hf_x REGION=us
treqs compute secrets list --target gpu-box
treqs compute secrets delete --target gpu-box WANDB_API_KEY
```

`--target` accepts a target ID, a unique name, or a unique ID prefix from `treqs compute targets list`.

Listing secrets shows key names, never values — once set, a secret cannot be read back out of TReqs. To rotate one, set it again with the new value.

A workflow has to declare which secrets it wants before they're exposed to its stages:

```yaml
name: train
secrets:
  - WANDB_API_KEY
  - HF_TOKEN
```

A secret that a workflow doesn't declare is not injected. See [Workflows](/docs/workflows).

Because secrets live on the compute target, every project in the organization that runs on that target gets them. If a key should not be that widely available, put it on a separate target.


---

# Training requests

> The review unit — what goes into one, how it gets approved, and how it moves through its statuses.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-file-terminal" class="size-16 text-primary"}
::

A **training request** is a proposal to run training. It's the central object in TReqs, it's where the name TReqs comes from. It works the way a pull request does: you describe what you want to run, hand it off for review, document pre-run analysis, and execute when ready.
::

The reason for the review step is cost and accountability. A training run can occupy expensive hardware for hours or days. A training request makes the plan legible — the exact code, the exact stages, the exact machine — before anyone spends that.

## What a request is made of

A training request ties together four things:

- **Project** it belongs to, which supplies the repository.
- **Code**: a source branch and, ultimately, a full immutable commit.
- **Workflow file** at that commit, the worflow defines the stages or tasks. See [Workflows](/docs/workflows).
- **Compute target** it will run on. See [Compute targets](/docs/compute-targets).

When a request is queued it produces a **training run**, which is the hand-off for execution.

## Creating a TR

From the dashboard, open a project and choose **New training request**. From the CLI:

```bash [TReqs CLI]
treqs tr create --title "Baseline run"
treqs tr create --title "Train v2" --workflow-path .treqs/workflows/train.yaml
treqs tr create --title "GPU run" --compute-target gpu-box --status open
```

## Status flow

| Status | Meaning |
| --- | --- |
| **Draft** | (Optional) Being written. Not up for review, not runnable. |
| **Open** | Up for review, and — once approved — queueable. |
| **Done** | Finished. Its run completed. |
| **Cancelled** | Abandoned. Closed without completing. |

## Opening for review

Opening a request is what puts it in front of reviewers. It requires a compute target — you can't ask someone to approve a run without saying where it will run:

```bash [TReqs CLI]
treqs tr open <request-id> --compute-target gpu-box
treqs tr open <request-id> --compute-target gpu-box --reviewer alice
```

An open request needs **at least one assigned reviewer** before any approve or reject decision will be accepted. Assign them when you open it, or add them afterwards — `--reviewer` adds to whoever is already on the request, and can be repeated.

## Review

Each assigned reviewer holds one of three states:

| Review state | Meaning |
| --- | --- |
| **Pending** | Assigned, hasn't decided yet. |
| **Approved** | Happy for this to run. |
| **Changes Requested** | Not yet — something needs to change first. |

Reviewers decide from the request page, or from the CLI:

```bash [TReqs CLI]
treqs tr review approve <request-id>
treqs tr review reject <request-id> # ' = "Changes Requested"
treqs tr comment <request-id> --body "Can we pin the dataset version?"
```

Reviewers are notified when they're assigned and when a request they're reviewing changes. See [Notifications](/docs/notifications).

## Who can configure review controls

The admins allowed to configure training request controls for an organization's projects is itself a setting, under **Configure → Permissions**. 

There are two modes:

- **All Admins** — any admin or owner of the organization can configure TR controls.
- **Specific Admins** — only the admins you name.

## Queueing

Once a request is Open and approved, queue it:

```bash [TReqs CLI]
treqs tr queue <request-id>
```

That creates a job and prints its ID. From there, [Training runs](/docs/training-runs) takes over.


---

# Workflows

> The YAML file that defines the stages of a training run.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-file-code-2" class="size-16 text-primary"}
::

A **workflow** is a YAML file in your repository that says what a training run actually does. Training requests point at one; runs execute it stage by stage.
::

Workflows live in the repo, not in TReqs. That's deliberate — the workflow is versioned with the code it runs, so a training request pinned to a commit gets exactly the workflow that existed at that commit.

Conventionally they live under `.treqs/workflows/`:

```
.treqs/workflows/train.yaml
```

## Shape

Every key that isn't reserved is a **stage**. There is no `steps:` or `jobs:` wrapper — the top level *is* the list of stages, and they run in the order written.

```yaml
name: train
working_directory: .
secrets:
  - WANDB_API_KEY

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

That workflow has three stages: `preprocess`, `train`, `evaluate`.

The reserved keys — everything that is *not* a stage — are:

| Key | Purpose |
| --- | --- |
| `name` | The workflow's name, shown in the dashboard. |
| `working_directory` | Directory to run stages from, relative to the repository root. Defaults to the root. |
| `secrets` | Names of compute target secrets to inject into the run's environment. |
| `environment` | Execution environment setup — currently a Python block. |

## Multi-command stages

A stage can be a list, in which case the commands run in sequence:

```yaml
train:
  - python -m pip install -e .
  - python train.py --config configs/base.yaml
```

## Python environment

The `environment.python` block asks TReqs to build a virtual environment before any stage runs:

```yaml
environment:
  python:
    version: "3.11"
    venv_path: .venv
    install_roar: true
    requirements:
      - -r requirements.txt
    build_requirements:
      - setuptools
      - wheel
```

- `version` — the Python version, as `major.minor`.
- `venv_path` — where the virtual environment is created. Stages run with it active.
- `install_roar` — install roar into the environment so the run captures lineage. Set this if you want the run to publish to GLaaS.
- `requirements` — passed to `pip install`. Entries can be package specifiers or `-r` pointers to a requirements file in the repo.
- `build_requirements` — installed first, for packages that need build tooling present before the main install.

## Secrets

`secrets` lists the names of secrets to pull from the compute target the run executes on. They arrive as environment variables:

```yaml
secrets:
  - WANDB_API_KEY
  - HF_TOKEN
```

Only declared secrets are injected. Naming a secret the target doesn't have is a configuration error — set it first with `treqs compute secrets set`, described in [Compute targets](/docs/compute-targets).

Never put secret *values* in the workflow file. It's in your repository; anyone who can read the repo can read it.

## Validating

Check a workflow against a compute target before opening a training request around it:

```bash [TReqs CLI]
treqs doctor --target gpu-box --workflow .treqs/workflows/train.yaml
```

`treqs doctor` validates the project binding, the git source, the workflow, and compute readiness together, which catches most of what would otherwise fail several minutes into a run.

## How a run uses it

When a training request is queued, TReqs clones the repository at the pinned commit, reads the workflow from that commit, builds the environment if one is declared, and executes each stage in order as a **task**. A failing stage fails the run and later stages are skipped.

Stage-level status is visible while the run executes — see [Training runs](/docs/training-runs).


---

# Publishing to GLaaS

> What a run records, who gets to see it, and how to republish lineage that didn't land.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-share-2" class="size-16 text-primary"}
::

A run doesn't only produce a model — it produces the *account* of how that model was made. Publishing sends that account to [GLaaS](https://glaas.ai), the registry that makes an artifact's lineage lookup-able by its content hash.
::

So later on, if you have a model and you want to recall the full context. Compute its hash, look it up in GLaaS to see it's full pipeline and all the inputs used, and click the link from GLaaS to the training request in TR that triggered it.

## What gets captured

If roar is installed on the compute target, the run captures lineage as its stages execute — what each stage read and wrote, at which commit.

Getting roar onto the target is the `install_roar` flag in your workflow's Python environment block, or `--install-roar` on an on-demand compute target. Without roar there, there's no lineage to publish regardless of the mode you choose.

## Visibility modes

What happens to that lineage afterwards is set per training request:

| Mode | Result |
| --- | --- |
| `disabled` | Nothing is published. |
| `private` | Published to GLaaS, linked to the project, visible only to people who can see the project. |
| `public` | Published publicly and attributed to your organization. |
| `public_anonymous` | Published publicly without attribution. |

Set it when creating the request:

```bash [TReqs CLI]
treqs tr create --title "Train v2" \
    --workflow-path .treqs/workflows/train.yaml \
    --lineage-mode private
```

The two public modes require confirmation — interactively, or with `--yes` in a script. That's deliberate: publishing publicly is not reversible in any meaningful sense, since anyone may have read it already. Think of `public` as the decision it is.

## Republishing

If a run completed but its lineage didn't reach GLaaS — a transient failure at publish time — you can republish without re-running:

```bash [TReqs CLI]
treqs jobs republish-lineage <job-id>
```


---

# Training runs

> Watching queued work execute — statuses, tasks, and logs.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-play" class="size-16 text-primary"}
::

A **run** is the execution of a training request. Queueing an approved request creates a run; the run picks up the specified compute target, clones your code, executes the workflow stages, and publishes what it produced.
::

## Statuses

A run moves through a lifecycle:

| Status | Meaning |
| --- | --- |
| **Queued** | Created, waiting for a compute target to pick it up. |
| **Assigned** | Matched to a target; the agent hasn't claimed it yet. |
| **Acquired** | The agent has claimed it and is preparing — cloning, building the environment. |
| **In Progress** | Workflow stages are executing. |
| **Completed** | Every stage finished successfully. |
| **Failed** | A stage failed, or the run couldn't be prepared. |
| **Stopped** | Cancelled before it finished. |

**Completed**, **Failed**, and **Stopped** are terminal.

A run sitting in **Queued** for a long time usually means no target is available: a dedicated target whose agent is offline, or an on-demand target that can't launch — often an invalid provider credential. Check the compute target's status first.

## Tasks

Each workflow stage becomes a **task**, with its own status: **Pending**, **Running**, **Completed**, **Failed**, or **Skipped**. Tasks run in the order the workflow lists them, and when one fails the rest are **Skipped** rather than attempted.

This is the fastest way to read a failed run — find the failed task, and you know which stage broke.

```bash [TReqs CLI]
treqs jobs tasks <job-id>
```

## Logs

A run's log has more than one producer, which matters when you're debugging.

```bash [TReqs CLI]
treqs jobs logs <job-id>              # the workload's own output
treqs jobs logs <job-id> --follow     # keep polling until complete
treqs jobs logs <job-id> --agent      # what the agent recorded
treqs jobs logs <job-id> --task <id>  # narrow to one stage
```

`--agent` is the one people forget. If a task fails *before its command runs* — a missing interpreter, a checkout that didn't resolve, an environment that wouldn't build — the workload log is empty and the explanation is in the agent log.

To follow a run from the terminal:

```bash [TReqs CLI]
treqs jobs watch <job-id>   # lifecycle on stderr, logs on stdout
treqs jobs wait <job-id>    # block until terminal; non-zero unless Completed
```

`treqs jobs wait` exits non-zero unless the run reaches **Completed**, which makes it usable in a script. Ctrl-C during `watch` detaches without cancelling the run.

## Stopping a run

```bash [TReqs CLI]
treqs jobs stop <job-id>
treqs jobs cancel <job-id>  # `cancel` is just an alias for `stop`
```

A stopped run lands in **Stopped** and keeps its logs and task history.


---

# Using the CLI

> Drive TReqs from a terminal — logging in, binding a repo to a project, and running the request lifecycle.

The `treqs` CLI does everything the dashboard does, and it's the better tool when you're already in a repository. Most commands are **repo-bound**: run them inside a git repo that's been bound to a project, and they infer the project, branch, and commit from where you are.

For the exhaustive command reference, run `treqs --help`, or `treqs <command> --help` for any subcommand. This page is the path through it.

::u-page-grid{class="lg:grid-cols-2 gap-4"}
:u-page-card{icon="i-lucide-box" title="TReqs CLI on Github" to="https://github.com/treqs/treqs-cli" target="_blank"}
::

## Global options

```
--version       Show the version and exit.
--api-url TEXT  TReqs API base URL.  [env var: TREQS_API_URL]
--json          Emit machine-readable JSON.
```

`--json` goes *before* the subcommand — `treqs --json whoami`, not `treqs whoami --json`. It's what makes the CLI scriptable.

## Log in

```bash [TReqs CLI]
treqs login
```

This starts a device authorization flow: it prints a URL and a code, you approve them in your browser, and the session is stored in your platform config directory. `--no-browser` skips trying to open one for you.

For CI, use an API token issued from the dashboard instead:

```bash [TReqs CLI]
treqs login --token treqs_pat_XXXXXXXX
echo $TOKEN | treqs login --token -   # read from stdin
```

To use a token *without* storing it, set `TREQS_API_TOKEN`. It takes precedence over any stored login — which is what you want in an ephemeral environment.

Check who you are, and which organizations you can act as:

```bash [TReqs CLI]
treqs whoami
```

It lists every owner you can act as — yourself plus your organizations — with your role and project count in each.

## Bind a repo to a project

```bash [TReqs CLI]
treqs projects list          # what you have access to
treqs project use my-project # bind the current repo
treqs project status         # what the current repo is bound to
```

`treqs project use` writes the binding into the repo, so the `tr` commands below know their context without you naming a project each time. `treqs project clear` removes it.

## Check before you run

```bash [TReqs CLI]
treqs doctor --target gpu-box --workflow .treqs/workflows/train.yaml
```

`doctor` validates your laptop, the project binding, the git source, the workflow, and compute readiness together. It's worth running before you open a training request — it catches the errors that would otherwise surface several minutes into a run, when a stage fails on a machine you're paying for.

## The training request lifecycle

```bash [TReqs CLI]
# Create a draft
treqs tr create --title "Baseline run" \
    --workflow-path .treqs/workflows/train.yaml

# Open it for review with a compute target and reviewers
treqs tr open <request-id> --compute-target gpu-box --reviewer alice

# Reviewers decide
treqs tr review approve <request-id>
treqs tr review reject <request-id>

# Queue the approved request; prints a job ID
treqs tr queue <request-id>
```

Also available: `treqs tr list`, `treqs tr show`, `treqs tr update`, `treqs tr comment`, and `treqs tr cancel`. See [Training requests](/docs/training-requests) for what the statuses mean.

## Follow the run

`treqs tr queue` prints a job ID. From there:

```bash [TReqs CLI]
treqs jobs watch <job-id>            # lifecycle + logs until it finishes
treqs jobs logs <job-id> --follow    # just the workload output
treqs jobs logs <job-id> --agent     # the agent's log — read this when a
                                     # task fails before its command runs
treqs jobs tasks <job-id>            # per-stage status
treqs jobs wait <job-id>             # block; non-zero unless Completed
```

`treqs jobs wait` is the one for scripts — it exits non-zero unless the run reaches **Completed**, so it fails a pipeline properly. `treqs jobs stop` cancels a run in flight.

## Manage compute

```bash [TReqs CLI]
treqs compute targets list
treqs compute targets create --name gpu-box
treqs compute targets create --kind on-demand --name burst \
    --type runpod --instance-type cpu3c
treqs compute targets registration-code create --target gpu-box
treqs compute targets instances burst
treqs compute targets archive gpu-box

treqs compute secrets set --target gpu-box WANDB_API_KEY=abc123
treqs compute secrets list --target gpu-box
treqs compute secrets delete --target gpu-box WANDB_API_KEY
```

`--target` accepts an ID, a unique name, or a unique ID prefix. See [Compute targets](/docs/compute-targets).

## Owner context

Most commands take `--owner` to say which organization to act in. It defaults to the repo's bound project owner, so inside a bound repo you rarely need it.

```bash [TReqs CLI]
treqs orgs list
treqs compute targets create --name team-gpu --owner acme
```

## Log out

```bash [TReqs CLI]
treqs logout
```


---

# Insights

> Training activity and compute utilization, across an organization or a single project.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-chart-line" class="size-16 text-primary"}
::

**Insights** aggregates what's been happening — who is running what, how long it takes, and what your compute is costing. It exists at two scopes, and they answer different questions.
::

## Organization insights

Under `/<org>/insights`, covering every project in the organization.

### Training Request Activity

Training requests over time, plus a **TR Leaderboard** of who is creating them. Useful for seeing whether review is actually happening or whether requests are piling up unreviewed.

### Run Activity

Runs over time, a **Run Leaderboard**, and a **histogram of compute time per training request**. The histogram is the interesting one: it shows the distribution rather than an average, so a handful of very long runs don't hide behind a reasonable-looking mean.

### Compute Utilization

Only at the organization scope, because [compute targets are organization-level](/docs/compute-targets). Dedicated and on-demand targets are reported separately, since the questions differ.

## Project insights

Under `/<org>/<project>/insights`, the same **Training Request Activity** and **Run Activity** views scoped to one project. There's no utilization view here — compute isn't owned by a project, so there's nothing project-shaped to report.

Use project insights to look at one workstream; use organization insights to compare across them or to make decisions about hardware.


---

# Notifications

> In-app and Slack notifications — what TReqs tells you about, and how to control it.

::div{class="flex items-start gap-6"}
::div{class="shrink-0 flex items-center justify-center mt-1 size-24 rounded-4xl bg-dim-200"}
:u-icon{name="i-lucide-bell" class="size-16 text-primary"}
::

TReqs notifies you about the things that nyou care about: a review you've been assigned, a comment on your training request, a run that finished or failed. Configure these as you like for email, Slack, and in-app in the Dashboard.
::

## What you get told about

Notifications are generated for training-request and run events:

| Event | Sent to |
| --- | --- |
| You were assigned as a reviewer | The reviewer |
| A review was approved | The request's author |
| Changes were requested on a review | The request's author |
| A comment was posted | People following the request |
| A run changed status | The request's author |

## Slack

Slack is configured per organization, under **Configure → Notifications**.

### Connecting the workspace

An organization admin installs the TReqs Slack app once:

1. Go to **Configure → Notifications**.
2. Choose **Connect to Slack**.
3. Authorize the app in the Slack workspace you want notifications in.

The page then shows the connected workspace and when it was installed. Disconnecting removes the installation for the whole organization, so every member stops receiving Slack notifications — it's not a personal setting.

### Your own preference

Connecting the workspace doesn't opt everyone in. Each member has their own **Enable Slack notifications** toggle on the same page, controlling whether *they* receive Slack messages from this organization.

So there are two switches, and both must be on: the organization's installation, and your personal preference. If you're not getting Slack messages, check yours before asking an admin about the installation.

Preferences are per organization. Being opted in for one organization says nothing about ano