Introduction

What Onus does, how to install it, and where to find each topic.

# Introduction

Onus turns a pull request into a short report of changes in meaning: new external services, contract changes, new relationships between components, weakened tests, broken rules. Every row is computed from the code by deterministic analysis, never generated, and links to the files and lines behind it. Onus only reads files: it never installs or runs the code it analyzes.

## Install

With Homebrew, on macOS or Linux:

```sh
brew install onushq/tap/onus
```

Or with the installer, which checks the download's SHA-256 and puts `onus` in `~/.local/bin`:

```sh
curl -fsSL https://onushq.com/install.sh | sh
```

Then, in a git repository:

```sh
onus report --base main --head HEAD
```

Archives for macOS, Linux and Windows are on the [releases page](https://github.com/onushq/onus/releases), and the GitHub Action reports on every pull request (see [CI](/docs/ci)).

## The guide

These pages are the guide that ships inside the `onus` binary: `onus help <topic>` prints any of them in the terminal, offline.

| Topic | What it covers |
| --- | --- |
| [getting-started](/docs/getting-started) | Install Onus, build a map and read your first report |
| [commands](/docs/commands) | Every command and flag, with examples and exit codes |
| [reports](/docs/reports) | Reading a report: rows, ranking, evidence, the changed lines tests ran and the JSON |
| [changes](/docs/changes) | Every kind and subkind of change Onus reports |
| [configuration](/docs/configuration) | The onus.yaml reference: components, rules, labels, extractors |
| [intent](/docs/intent) | Checking a change against its stated intent |
| [ci](/docs/ci) | Running Onus on every pull request, and outcome records kept by CI |
| [agents](/docs/agents) | The map for coding agents: onus mcp, its tools, many agents and worktrees |
| [scopes](/docs/scopes) | Task tokens, the git gateway, escalation with evidence and the audit log |
| [lanes](/docs/lanes) | Risk lanes, change submissions, the learned model, the verifying judge, outcome records and provenance |
| [production](/docs/production) | Production signals, rollout plans per lane and automatic rollback |
| [web-interface](/docs/web-interface) | The web interface: onus ui opens all of it in your browser |
| [environments](/docs/environments) | Environments built from a commit, the evidence store, traces and coverage into the map, and the behavior diff |
| [cloud](/docs/cloud) | Onus Cloud from the CLI: onus login, scoped tokens, hosted environments, evidence, escalations, maps and agents |
| [plugins](/docs/plugins) | New languages and frameworks, SCIP indexes, language servers, trusted mode |
| [how-it-works](/docs/how-it-works) | How maps are built and compared |
| [troubleshooting](/docs/troubleshooting) | Map confidence notes, common questions and current limits |

The source is in the [onus repository](https://github.com/onushq/onus/tree/main/crates/onus-cli/guide).

Onus turns a pull request into a short report of changes in meaning: new external services, contract changes, new relationships between components, weakened tests, broken rules. Every row is computed from the code by deterministic analysis, never generated, and links to the files and lines behind it. Onus only reads files: it never installs or runs the code it analyzes.

Install

With Homebrew, on macOS or Linux:

brew install onushq/tap/onus

Or with the installer, which checks the download's SHA-256 and puts onus in ~/.local/bin:

curl -fsSL https://onushq.com/install.sh | sh

Then, in a git repository:

onus report --base main --head HEAD

Archives for macOS, Linux and Windows are on the releases page, and the GitHub Action reports on every pull request (see CI).

The guide

These pages are the guide that ships inside the onus binary: onus help <topic> prints any of them in the terminal, offline.

Topic	What it covers
getting-started	Install Onus, build a map and read your first report
commands	Every command and flag, with examples and exit codes
reports	Reading a report: rows, ranking, evidence, the changed lines tests ran and the JSON
changes	Every kind and subkind of change Onus reports
configuration	The onus.yaml reference: components, rules, labels, extractors
intent	Checking a change against its stated intent
ci	Running Onus on every pull request, and outcome records kept by CI
agents	The map for coding agents: onus mcp, its tools, many agents and worktrees
scopes	Task tokens, the git gateway, escalation with evidence and the audit log
lanes	Risk lanes, change submissions, the learned model, the verifying judge, outcome records and provenance
production	Production signals, rollout plans per lane and automatic rollback
web-interface	The web interface: onus ui opens all of it in your browser
environments	Environments built from a commit, the evidence store, traces and coverage into the map, and the behavior diff
cloud	Onus Cloud from the CLI: onus login, scoped tokens, hosted environments, evidence, escalations, maps and agents
plugins	New languages and frameworks, SCIP indexes, language servers, trusted mode
how-it-works	How maps are built and compared
troubleshooting	Map confidence notes, common questions and current limits

The source is in the onus repository.