rex-cli

Command-line interface for the rex-orchestrator MCP server. Submit tasks, watch them run, read results, cancel work, check health — all from any terminal.

Zero-install via npx, or install globally with npm install -g.

Install

Option 1 — zero install via npx (recommended)

No clone, no global install, no auth. Just run:

npx rex-orchestrator-cli@latest health

The first invocation downloads the package from npm and runs it; subsequent runs are cached. Works from any directory, any machine with Node 18+.

Option 2 — install globally from npm

npm install -g rex-orchestrator-cli

You now have rex on your PATH. Verify:

rex --help

Option 3 — run from a clone (for CLI development)

git clone https://github.com/cgoodsell68/rex-orchestrator.git
cd rex-orchestrator/cli
node cli.js health

Configure

Set two environment variables (once, in your shell rc file):

export REX_MCP_URL="https://rex-orchestrator-production.up.railway.app/mcp"
export REX_MCP_TOKEN="<your REX_MCP_TOKEN value>"

Or pass per-call overrides:

rex --url=https://example.com/mcp --token=abc123 health

Commands

| Command | Purpose | |---|---| | rex submit "<text>" | Submit a new task to the orchestrator | | rex list | List recent tasks with optional filters | | rex get <task_id> | Show full detail for one task including logs and result | | rex stream <task_id> | Tail logs and status for a task until it terminates | | rex cancel <task_id> | Cancel a queued or running task | | rex health | Show orchestrator health + worker lag | | rex help | Print usage |

Global flags

| Flag | Description | |---|---| | --json | Output raw JSON instead of human-readable format | | --url=URL | Override REX_MCP_URL | | --token=TOKEN | Override REX_MCP_TOKEN |

Examples

Submit a task

rex submit "Deploy v2 and run smoke tests" --priority=high

Output:

✓ Task submitted
  id:      6d44f195-cf02-4f19-ba3f-6a063814896a
  title:   Deploy v2 and run smoke tests
  status:  queued
  created: 2026-04-08T07:12:00.000Z

  Track with: rex get 6d44f195-cf02-4f19-ba3f-6a063814896a
  Stream:     rex stream 6d44f195-cf02-4f19-ba3f-6a063814896a

Flags:

• --title="Short title" — explicit title (default: first 80 chars of content)
• --priority=low|normal|high — default normal
• --source=<instance> — default rex-cli
• --visibility=private|shared|public — default shared

List tasks

# Recent 20
rex list

# Only running tasks
rex list --status=running

# From a specific instance
rex list --source=uriel-rex --limit=50

# Since a timestamp
rex list --since=2026-04-08T00:00:00Z

# Raw JSON for piping into jq
rex list --json | jq '.tasks[].task_id'

Sample output:

5 tasks

  6d44f195  completed   uriel-rex           2h ago      Deploy v2 and run smoke tests
  a12c8979  running     claude-code-rex     30s ago     Design speech-to-text UI
  2636736c  completed   uriel-rex           1d ago      Design accessible UI specifications
  dc8a6484  failed      uriel-rex           3d ago      Add accessible on-screen instructions
  5ee3c180  cancelled   rex-cli             1w ago      Cross-instance test

Get full task detail

rex get 6d44f195-cf02-4f19-ba3f-6a063814896a

Shows: title, status, source, priority, timestamps, content, logs, error (if any), and full result.

Stream a task (tail logs live)

rex stream 6d44f195-cf02-4f19-ba3f-6a063814896a

Polls every 2 seconds (configurable with --interval=5). Prints new log entries as they appear and exits when the task reaches completed, failed, or cancelled.

Cancel a task

rex cancel 6d44f195-cf02-4f19-ba3f-6a063814896a --reason="superseded by v3"

Refuses if the task is already completed, failed, or cancelled.

Health check

rex health

● online uptime 45231s
  tasks:        398 completed  2 queued  1 running
  active Rex:   3
  worker lag:   0s
  MCP servers:  supabase(5), github(35)

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Generic error — bad args, network, MCP error, auth failure | | 2 | Task not found (for get, cancel, stream) |

Scripting

All commands support --json for machine-readable output. Exit codes are non-zero on error, so you can chain commands in scripts:

#!/bin/bash
task_id=$(rex submit "Nightly QA run" --priority=normal --json | jq -r '.task_id')
rex stream "$task_id" || {
  echo "QA failed"
  exit 1
}
echo "QA passed"

Or watch a queue and act on each new task:

while true; do
  rex list --status=queued --json | jq -r '.tasks[].task_id' | while read id; do
    echo "Picking up $id"
    # do something with $id
  done
  sleep 10
done

Transport details

Under the hood, rex speaks MCP JSON-RPC 2.0 over streamable HTTP directly — no MCP SDK dependency. Each subcommand is a single tools/call request; responses come back as Server-Sent Events and are parsed inline.

The six underlying MCP tools:

| Subcommand | MCP tool | |---|---| | rex submit | rex_submit_task | | rex list | rex_list_tasks | | rex get | rex_get_task | | rex stream | rex_get_task (polled every 2s) | | rex cancel | rex_cancel_task | | rex health | rex_health |

Note: rex stream uses polling rather than true SSE streaming because the current rex_stream_task tool returns snapshots. When the orchestrator adds real streaming, this subcommand will switch transparently.

Troubleshooting

Unauthorized — set REX_MCP_TOKEN or pass --token= The MCP endpoint rejected your request. Make sure REX_MCP_TOKEN is set in your environment and matches the value in Railway.

MCP HTTP 500: ... The orchestrator had an internal error. Check Railway logs for [MCP] Error handling request.

Could not parse MCP response: ... The server returned something that isn't valid JSON or SSE. Usually a deploy in flight — retry in 30 seconds.

Task not found: <id> The task id doesn't exist in rex_tasks. Check the id with rex list.

License

MIT