ProveAI Origin
Try it
cookbookbeginner7 min readUpdated 2026-05-27

Use the rj CLI

Drive ProveAI Origin from the terminal — log in, list agents, inspect tests, fetch runs, and read the judge headline without leaving your shell.

Use the rj CLI

The rj command-line interface is the terminal half of P8 from the AI-native principles ADR: if you can click it, you can curl it. Every read available in the agent-page UI is also rj <noun> <verb>, and Sprint 15's MCP write tools give you the same write surface from curl / your editor / your CI.

Sprint 14 shipped 5 read commands (agents, tests, runs, headline, whoami). Sprint 15 added rj login so you no longer have to copy a token by hand, and exposed the 4 write actions (snapshots.capture, runs.trigger, settings.update, cluster.dismiss) over MCP — covered in Automate with MCP write tools. Write-shaped CLI subcommands wrapping those MCP tools land in Sprint 16+.

Install

# Once published (post Sprint 15 npm publish):
pnpm add -g @runtime-judgement/cli

# Today, from source:
git clone https://github.com/rambo-01/runtime-judgement-app
cd runtime-judgement-app
pnpm install
pnpm --filter @runtime-judgement/cli build
alias rj="node $(pwd)/packages/rj-cli/dist/index.js"
rj --help

The post-install path will land an rj binary on your PATH once the package is on npm (tracked in dev-docs/runbooks/2026-05-22-mcp-publish.md).

Log in (recommended first step)

rj login

Opens your browser, mints a fresh rj_live_... token, writes it to ~/.rj/token with 0600 perms, then runs the connectivity check so you immediately know the token works. Headless / SSH:

rj login --paste

Full walkthrough — including port-conflict + browser-blocking pitfalls + multi-environment --base-url — in Log the rj CLI in.

Expected output:

rj login
  base URL   https://runtime-judgement-app.vercel.app
  wrote token to /Users/you/.rj/token
  verifying…
rj
  base URL   https://runtime-judgement-app.vercel.app
  token      rj_live_abcd…wxyz
  OK
rj login: success.

Manual config (alternative)

If you'd rather not use rj login, the CLI also resolves config in this order:

  1. RJ_BASE_URL env var (default: https://runtime-judgement-app.vercel.app)
  2. RJ_AUTH_TOKEN env var, OR
  3. The contents of ~/.rj/token (one line, no quotes)

Generate a token at /app/settings/api-keys and either export RJ_AUTH_TOKEN=rj_live_... per shell or paste it into ~/.rj/token (mode 0600). rj whoami reports which source the loaded token came from.

The five commands

rj agents list

List every agent you own. Default output is a table; --json dumps the raw JSON-RPC result for scripting.

rj agents list
rj agents list --limit 5
rj agents list --json | jq '.agents[].id'

ID                       NAME             LAST RUN              HEALTH
-----------------------  ---------------  --------------------  ----------
agt_demo_cx_support      cx-support       2026-05-26T17:42:00Z  regressed
agt_demo_payments        payments-agent   2026-05-26T16:11:09Z  green

health color-codes by the agent's most-recent run: green (passing), yellow (drifting — accepted-intentional changes), red (regressed — at least one CHANGED-UNEXPECTED).

rj tests list <agent-id>

List tests attached to one agent. --filter is a case-insensitive substring match on test name.

rj tests list agt_demo_cx_support
rj tests list agt_demo_cx_support --filter "order"
rj tests list agt_demo_cx_support --json

Each row shows the test id, name, parent suite (or — if unfiled), health bucket (healthy / regressing / accepted / no-runs), and the last verdict.

rj runs get <run-id>

Fetch the full per-test breakdown for one snapshot run.

rj runs get run_01HZ123...
rj runs get run_01HZ123... --json | jq '.perTest[] | select(.verdict != "PASSED")'

The JSON output is the same RunSummary shape the MCP runs.get tool returns — useful for piping into a dashboard or a Slack incident channel.

rj headline get <agent-id> [--section]

Read the judge-authored P1 headline for an agent section. Defaults to overview; other sections are tests, suites, runs, pipeline, settings (the six tabs from the agent-page IA ADR).

rj headline get agt_demo_cx_support
rj headline get agt_demo_cx_support --section pipeline
rj headline get agt_demo_cx_support --json

The headline carries confidence (capped at 0.99 by P9), citations (the spans / runs / commits that justify the claim), and a cached boolean so you know whether you paid the regen cost. A typical overview reads like:

cx-support is regressing on 2 of 14 tests since Cursor PR #243, 12 min ago.
  confidence  0.84  (high)
  cached      false
  citations
    run/01HZRUN... — search-tool returns empty (CHANGED-UNEXPECTED)
    run/01HZRUN... — planner-goal-deviation (CHANGED-UNEXPECTED)

rj whoami

Diagnostic — prints the resolved base URL + truncated token, then runs the connectivity check.

rj whoami

Use this first whenever a command fails — it isolates auth/connectivity from tool-specific errors.

Architecture

The CLI POSTs JSON-RPC envelopes to /api/mcp — the same surface Use RJ from Claude Code via MCP documents. One command = one tool call = one HTTP round-trip.

  • src/commands/ — one file per noun (agents.ts, tests.ts, runs.ts, headline.ts, whoami.ts). Each exports both a commander.Command and a run...() function so tests can call the logic without parsing argv.
  • src/mcp-client.ts — tiny custom client. The official @modelcontextprotocol/sdk is overkill for a single-shot HTTP POST; a future rj watch or rj stream command will upgrade to the SSE substrate.

Write actions (via MCP today; CLI subcommands Sprint 16+)

Sprint 15 ships 4 MCP write tools — same surface, same auth, same audit log as the UI. Until the CLI grows native subcommands they're available via direct JSON-RPC against /api/mcp (your token from rj login works as-is). Full walkthrough in Automate with MCP write tools.

# Capture a trace as a regression-test snapshot
curl -s -X POST https://runtime-judgement-app.vercel.app/api/mcp \
  -H "Authorization: Bearer $(cat ~/.rj/token)" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "snapshots.capture",
      "arguments": {
        "agentId": "01HZAGENT...",
        "traceId": "01HZTRACE...",
        "name": "Refund flow regression"
      }
    }
  }' | jq '.result.structuredContent'

# Queue a suite run
curl -s -X POST https://runtime-judgement-app.vercel.app/api/mcp \
  -H "Authorization: Bearer $(cat ~/.rj/token)" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "runs.trigger",
      "arguments": {
        "agentId": "01HZAGENT...",
        "suiteId": "01HZSUITE...",
        "triggerKind": "manual"
      }
    }
  }' | jq '.result.structuredContent'

Every write consults the per-action permission tier (auto-allowed / propose-only / read-only) and appends to audit_log (P10). The four available writes are snapshots.capture, runs.trigger, settings.update, and cluster.dismiss.

Pitfalls

fetch not available

Node 18+ ships globalThis.fetch. On older runtimes the CLI throws global fetch is not available. Upgrade to Node 18+.

401 unauthorized

Token is missing or malformed. Run rj whoami to see what's loaded. Regenerate from /app/settings/api-keys if you've lost the original.

limit flag is parsed but ignored

The --limit flag passes through to the MCP tool, but agents.list and tests.list cap at 500 server-side regardless. For pagination, future write tools will add cursor support.

Next steps

Related articles

Try it

AgentsSettings