Reference

CLI Reference

Full reference for all ribix CLI commands. Install with npm install -g @ribix/cli, then run ribix login to get started.

Command overview

Command	What it does
ribix login	Authenticate your CLI with Ribix.
ribix connect	Connect a staging environment to your workspace.
ribix run	Trigger a proactive agent run against the connected staging environment.
ribix findings	List findings for your workspace.
ribix show	Show full detail for a finding: severity, description, failing test, proposed fix diff, and current status.
ribix approve	Approve a finding and its proposed fix.
ribix reject	Reject a finding.
ribix watch	Open a live event stream for your workspace.
ribix status	Print workspace health information: connected staging URL, auth type, active workspace, GitHub App connection state, test framework, and pending finding count.

Commands

connect

Connect a staging environment to your workspace. Ribix prompts for the auth method and stores the configuration locally.

Syntax

ribix connect <url>

Flags

--auth <type>Auth type: bearer, cookie, or none (default: prompted)

--token <value>Bearer token value (skips interactive prompt)

--framework <name>Pin test framework: jest, vitest, pytest, or go

--name <name>Human-readable label for this environment

Examples

ribix connect https://staging.example.com
ribix connect https://staging.example.com --auth bearer --token $STAGING_TOKEN
ribix connect https://staging.example.com --framework vitest

run

Trigger a proactive agent run against the connected staging environment. By default runs all agent types (browser, API, code quality, design).

Syntax

ribix run [options]

Flags

--watchStream findings to terminal as they are discovered

--browser-onlyRun only the browser agent (skip API and code agents)

--severity <levels>Only report findings at or above this severity: p0, p1, p2, p3

--timeout <ms>Maximum run duration in milliseconds (default: 600000)

Examples

ribix run
ribix run --watch
ribix run --browser-only --watch
ribix run --severity p0,p1

findings

List findings for your workspace. By default shows the 20 most recent findings across all severities.

Syntax

ribix findings [options]

Flags

--pendingShow only findings awaiting approval

--severity <levels>Filter by severity: p0, p1, p2, p3 (comma-separated)

--limit <n>Maximum number of results to return (default: 20)

--jsonOutput as newline-delimited JSON

Examples

ribix findings
ribix findings --pending
ribix findings --severity p0,p1
ribix findings --pending --json

show

Show full detail for a finding: severity, description, failing test, proposed fix diff, and current status.

Syntax

ribix show <id>

Flags

--diffPrint only the fix diff (useful for piping)

--jsonOutput as JSON

Examples

ribix show find_abc123
ribix show find_abc123 --diff

approve

Approve a finding and its proposed fix. Opens a GitHub PR with the failing test and fix diff. Ribix runs your test suite one final time before creating the PR.

Syntax

ribix approve <id>

Flags

--skip-verifySkip final test-suite run (not recommended)

Examples

ribix approve find_abc123

reject

Reject a finding. The finding is marked as rejected and excluded from future duplicate detection.

Syntax

ribix reject <id> [options]

Flags

--reason <text>Free-text rejection reason (stored for workspace history)

Examples

ribix reject find_abc123
ribix reject find_abc123 --reason "Not reproducible in our stack"

watch

Open a live event stream for your workspace. Prints agent events, enrichments, and finding updates as they arrive in real time.

Syntax

ribix watch [options]

Flags

--events <types>Filter event types: agent, enrichments, all (default: all)

Examples

ribix watch
ribix watch --events agent
ribix watch --events enrichments

status

Print workspace health information: connected staging URL, auth type, active workspace, GitHub App connection state, test framework, and pending finding count.

Syntax

ribix status

Examples

ribix status

Global flags

These flags are available on every command:

--help, -hPrint help for the current command

--version, -vPrint CLI version

--workspace <id>Override the active workspace for this invocation

--no-colorDisable color output

Exit codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Authentication required (run ribix login)
`3`	No staging environment connected (run ribix connect)
`4`	Finding not found
`5`	Workspace not found

The CLI sources workspace configuration from ~/.ribix/config.json. You can override the active workspace per-command with --workspace <id> without touching the file.