RIO
Docs

Docs

Everything you need to get Rio reviewing your pull requests, or running locally from the CLI.

Introduction

Rio is an automated code review tool. It reads the diff of a change, inspects it against the repository's configuration, and reports concrete findings — security issues, error-prone patterns, and likely bugs — on the exact lines that cause them.

Rio has two surfaces:

  • GitHub App — reviews every pull request automatically with inline comments, a summary, and an optional pass/fail check.
  • CLI — reviews staged, uncommitted, or committed changes locally.

Rio is open architecture, not a black box — the GitHub App, worker, and AI engine are separate services that only talk over HTTP. Self-hosting docs are on the way; for now, the hosted version is the easiest way to run Rio.

Getting started
Two ways to use Rio — pick one or use both.

Installation

GitHub App

Install the app on a repo and Rio reviews every pull request automatically.

Install on GitHub

CLI

Requires Python 3.12+.

uv tool install rio-cli

Verify it works:

rio --help

Quickstart

With the CLI, your first review is three steps:

  1. Create an API key from your dashboard.
  2. Authenticate the CLI — it validates your key and stores it in your platform's Rio config file (see its exact location below):
    rio auth
  3. Review staged changes from inside any git repository:
    rio review --staged

With the GitHub App, it's just: install the app, open a pull request, and read the comments it leaves on your diff.

GitHub App

Installing the app

Head to the install page, sign in, and grant Rio access to the repositories you want reviewed. You can pick all of a user's or org's repos, or a specific subset, and you can revoke or edit access at any time from GitHub's app settings.

Repositories added to the app later are picked up automatically — no reinstall needed.

How reviews work

When a pull request is opened or updated, the GitHub App hands the job to Rio's worker, which:

  1. Builds the diff between the base and head of the PR.
  2. Reads .rio.yml from the exact commit being reviewed.
  3. Sends both to the AI engine, which returns findings scoped to changed lines.
  4. Posts the findings as inline comments, adds a summary comment, and — if configured — creates a GitHub Check Run.
CLI

Installation

uv tool install rio-cli

If you're using plain pip outside a virtual environment and run into permission errors, either use uv or create a virtualenv first.

Authentication (API keys)

  1. Create a key from your dashboard.
  2. Run rio auth and paste it when prompted:
    rio auth

rio auth checks the key against Rio before saving it, then writes it to your platform's Rio config file:

Config file location

  • Linux~/.config/rio/config.toml
  • macOS~/Library/Application Support/rio/config.toml
  • Windows%APPDATA%\rio\config.toml

The directory is created automatically on first run. On POSIX the file is written with 0600 permissions; on Windows it lives under your already-private %APPDATA%.

Alternatively, write that file yourself:

[api] api_key = "rio_..."

Before your first review, connect a Groq or OpenRouter key in the dashboard's settings so Rio can call your chosen LLM. Reviews fail with a clear error until one is configured.

Keep this file private — anyone with your key can use your account's review quota. Revoke a key any time from the dashboard if it's ever exposed.

Commands reference

Run from inside any git repository.

rio review --staged

Reviews changes that are staged (git add-ed) but not yet committed.

rio review --uncommitted

Reviews all uncommitted changes in the working tree, staged or not.

rio review --committed

Reviews commits on your current branch that haven't been pushed to its upstream yet.

rio review --diff path/to/file.diff

Reviews a diff from a file instead of your working tree — useful for CI or scripting.

rio review --include-untracked

Add this to any of the above to also review new, untracked files (treated as entirely-added diffs).

rio review

With no flags, reviews committed-but-unpushed changes plus anything uncommitted — whichever exist.

Configuration

.rio.yml reference

Drop this file at the root of your repo to tune what Rio comments on. Every field is optional — an absent or missing file just means Rio uses these defaults.

# .rio.yml — place at the root of your repo ignore_paths: - "vendor/**" - "**/*.generated.ts" # Findings below this severity are dropped before Rio comments. # One of: critical, warning, info min_severity: warning # Caps the number of inline comments Rio leaves on a single PR. # If more findings pass the severity filter than this, the most # severe ones are kept and the rest are silently dropped. max_comments_per_pr: 10 # If true, Rio creates a GitHub Check Run on each PR that fails # whenever the review finds any critical-severity issue. Off by # default — turning this on is what lets you require Rio to pass # via GitHub's branch protection settings. require_check: false

ignore_paths

List of glob patterns. Files matching any pattern are excluded before Rio ever sees them. Default: none.

min_severity

One of critical, warning, info. Findings below this are dropped. Default: info (nothing filtered).

max_comments_per_pr

Caps inline comments per review. Most severe findings are kept first. Default: 10.

require_check

If true, Rio creates a GitHub Check Run that fails when the review finds any critical issue. Default: false.

This file is read from the exact commit being reviewed, so a PR that changes .rio.yml takes effect on itself.

require_check only creates the check — it doesn't block merging by itself. To actually require it, go to your repo's Settings → Branches → Branch protection rules, edit (or add) a rule for your target branch, and add Rio under "Require status checks to pass before merging."

Guides

Best practices

  • Ignore generated code. Add build output, vendored deps, and generated files to ignore_paths so Rio focuses on code a human will actually review.
  • Set a severity floor. Start with min_severity: warning to keep reviews focused, then widen as Rio earns trust.
  • Gate CI on critical issues. Turn on require_check and require the Rio check via branch protection for a hard gate on merge.
  • Keep scopes small. Review staged changes with --staged while working, and use --diff file.diff in CI scripts.

Troubleshooting

  • Error: not authenticated. Run rio auth first. — the CLI has no key, or the key was revoked. Run rio auth with a key from your dashboard.
  • No LLM provider configured for this account. — connect a Groq or OpenRouter key in the dashboard's settings before reviewing.
  • could not connect to ai-engine at ... — the CLI can't reach the API. Check the url in your Rio config file (location varies by OS — see the CLI section above), or re-run rio auth.
  • Reviews silently skip files or take long — very large diffs are capped to protect responsiveness. Prefer reviewing smaller, focused scopes.
  • Installation permission errors — use uv tool install rio-cli or install into a virtual environment.
Changelog

rio-cli 0.2.2

  • Cross-platform config: the file now resolves per OS —~/.config/rio/config.toml on Linux, ~/Library/Application Support/rio/config.toml on macOS, and %APPDATA%\rio\config.toml on Windows — instead of a hardcoded Linux path.
  • Requires Python 3.12+ (removed the upper version cap).

rio-cli 0.2.0

  • New rio auth command — validates your API key and stores it securely.
  • Bring-your-own-key: reviews now use an LLM key you connect in the dashboard.
  • Published to PyPI — install via pip or uv.

rio-cli 0.1.0

  • Initial release: rio review with staged, uncommitted, committed, diff-file, and untracked scopes.