Skip to content

Getting Started

Quick Start

Get Ribix running against your staging environment in under five minutes. Ribix acts like a real user - clicking, submitting forms, calling APIs - and files a detailed bug report with a failing test and a proposed fix for everything it finds.

Prerequisites

  • A GitHub repository - Ribix connects your codebase to write tests and open PRs.
  • A staging environment URL (e.g. https://staging.example.com) - must be HTTPS and reachable from Ribix infrastructure.
  • Node.js 18+ for the CLI.

Install & connect

1

Install the Ribix CLI

npm install -g @ribix/cli
2

Authenticate

Opens a browser window for GitHub OAuth. Your workspace token is stored locally.

ribix login
3

Connect your staging environment

ribix connect https://staging.example.com

Ribix will prompt for an auth type (bearer token, session cookie, or none). You can update this later with ribix connect --auth bearer.

4

Run Ribix

ribix run --watch

The --watch flag streams findings to your terminal as they are discovered. Omit it for a single run that exits when complete.

What you should see:

terminal
✓ Connected to https://staging.example.com
  Scanning: browser flows, API endpoints, code quality

  [run #1] Navigating checkout flow...
  [run #1] Navigating auth flow...
  [run #1] Scanning API endpoints...

  Finding: P1 - TypeError on checkout submit  [find_abc123]
    → Failing test written
    → Fix generated
    → Full suite passed (42/42)
    → Ready to approve

  Run complete. 1 finding.
  Review: ribix show find_abc123
  Approve: ribix approve find_abc123

If Ribix finds nothing, it exits cleanly with a 0 findings summary. That is a good result - it means the scanned flows are currently clean.

What happens next

Once ribix run starts, Ribix moves through a five-stage loop:

1. Connect

Ribix authenticates against your staging URL and builds a sitemap of pages and API endpoints to explore.

2. Run

The browser agent navigates flows - checkout, forms, API calls - behaving like a real user. API and code quality agents run in parallel.

3. Findings

Each anomaly is classified by severity (P0–P3), described in plain English, and linked to the exact code path.

4. Approve

For each finding, Ribix writes a failing test, generates a fix diff, and runs your full test suite. You review and approve.

5. PR

One click opens a GitHub PR with the test + fix. Ribix never opens a PR without explicit approval from you.

Your first finding

When Ribix discovers a bug it creates a finding. Here is what a typical finding looks like - a severity badge, plain-English description, proposed diff, and an approve/reject decision:

P1TypeError: Cannot read 'total' on checkout

The checkout summary renders before the cart totals are resolved. When CartStore.total is undefined during the first render, the component throws before the user can complete purchase.

Proposed fix

- const total = CartStore.total;+ const total = CartStore.total ?? 0;

You can also review and approve findings from the CLI:

# List pending findings
ribix findings --pending

# View a specific finding
ribix show find_abc123

# Approve (opens the PR)
ribix approve find_abc123

Ribix never creates a PR without your approval.

Every fix goes through the approve/reject gate. You always review the diff and test results first.

Next steps

  • How It Works - deep dive into the agent architecture, modes, and frameworks.
  • CLI Reference - full command listing with flags and examples.
  • Integrations - GitHub App setup, staging requirements, test framework detection.