CLI Reference

rax is the artisan command line for Reactive Agents.

Rax stands for Reactive Agents Executable. Think of it as the Reactive Agents equivalent of Laravel’s Artisan CLI.

Use it to scaffold projects, generate agents, run and stream tasks, inspect runtime state, serve A2A endpoints, and deploy across local and cloud targets.

For workflow-first onboarding, start with Rax CLI.

Commands

rax init

Create a new Reactive Agents project.

rax init <name> [--template minimal|standard|full]

Templates:

All templates install the single unified reactive-agents package — no need to install individual @reactive-agents/* packages separately.

Template	What’s scaffolded
minimal	reactive-agents + bare agent that answers questions
standard	reactive-agents + adaptive reasoning, tools, observability dashboard
full	reactive-agents + reasoning, tools, memory, guardrails, cost, health check

Generated src/index.ts imports from "reactive-agents" and is runnable immediately after bun install && cp .env.example .env.

rax create agent

Generate an agent file from a recipe, or use --interactive for guided scaffolding.

rax create agent <name> [--recipe basic|researcher|coder|orchestrator]
rax create agent <name> --interactive

Recipes:

Recipe	What It Generates
basic	Minimal agent with LLM only
researcher	Agent with memory + reasoning
coder	Agent optimized for code tasks
orchestrator	Multi-agent orchestrator with memory

Interactive mode:

The --interactive flag launches a readline-based wizard (TTY only) that prompts for:

1. Agent name — defaults to the first positional argument if you pass one (e.g. rax create agent my-agent --interactive).
2. Provider — one of anthropic, openai, ollama, or gemini (same set the wizard validates today).
3. Recipe — basic, researcher, coder, or orchestrator.
4. Features — comma-separated list; default reasoning,tools. This is collected for the session; the generated file is determined only by the recipe (templates live in apps/cli/src/generators/agent-generator.ts). Adjust .withProvider(), .withModel(), and builder flags in the generated source after scaffolding if you need a different stack.

$ rax create agent my-agent --interactive

Create Agent (Interactive)
? Agent name: my-research-agent
? Provider [anthropic/openai/ollama/gemini]: anthropic
? Recipe [basic/researcher/coder/orchestrator]: researcher
? Features (comma-separated) (reasoning,tools): reasoning,tools

✔ Created: src/agents/my-research-agent.ts

rax run

Run an agent with a prompt.

rax run <prompt> [--provider anthropic|openai|ollama|gemini|litellm|test]
          [--model <model>] [--name <name>] [--tools] [--reasoning] [--stream] [--cortex]

--cortex: Enables .withCortex() on the builder so run lifecycle events are sent to a local Cortex companion studio (WebSocket ingest). Cortex is available as a public npm package (@reactive-agents/cortex). For npm-installed CLI: bun add @reactive-agents/cortex && rax cortex. For repo contributors: bun cortex (runs from source with hot reload). Set CORTEX_URL to the HTTP base (default http://127.0.0.1:4321).

Example:

rax run "Explain quantum computing" --provider anthropic --model claude-sonnet-4-6

Cortex (companion studio)

Cortex is available as a public npm package and from source.

From npm (recommended for users):

bun add @reactive-agents/cortex
rax cortex
# Opens http://127.0.0.1:4321 in your browser

From source (for contributors with hot reload):

git clone https://github.com/tylerjrbuell/reactive-agents-ts
cd reactive-agents-ts
bun install
bun cortex
# API on http://localhost:4321 — UI on http://localhost:5173 (hot reload)

Then in another terminal:

rax run "Research topic" --cortex --provider anthropic

Variable	Purpose
CORTEX_PORT	API listen port (default 4321)
CORTEX_NO_OPEN	Set to 1 to skip opening a browser
CORTEX_URL	Base URL the agent uses to reach Cortex ingest

rax serve

Start an agent as an A2A server.

rax serve [--port <number>] [--name <name>] [--provider <provider>] [--model <model>]
          [--with-tools] [--with-reasoning] [--with-memory]

Options:

Option	Default	Description
--port	3000	HTTP port for the A2A server
--name	"agent"	Agent name (used in Agent Card)
--provider	"test"	LLM provider
--model	—	Model name
--with-tools	off	Enable built-in tools on the A2A server agent (file-write, web-search, etc.)
--with-reasoning	off	Enable reasoning strategies
--with-memory	off	Enable memory. With no extra token: default tier (.withMemory()). Pass enhanced or 2 immediately after the flag for full four-layer memory with embeddings (.withMemory({ tier: "enhanced" })). Optional basic or 1 after the flag keeps the default tier and consumes that token (same behavior as omitting it).

Endpoints served:

• GET /.well-known/agent.json — Agent Card (A2A discovery)
• GET /agent/card — Agent Card (fallback)
• POST / — JSON-RPC 2.0 (message/send, tasks/get, tasks/cancel, agent/card)

Example:

rax serve --name researcher --provider anthropic --model claude-sonnet-4-6 --with-tools --port 4000

rax discover

Fetch and display the Agent Card from a remote A2A-compatible agent server.

rax discover <url>

Fetches GET <url>/.well-known/agent.json and pretty-prints the agent’s name, description, capabilities, and supported skills.

Example:

rax discover http://localhost:3000

Agent Card: researcher
  Provider: anthropic (claude-sonnet-4-6)
  Capabilities: streaming, tools
  Skills: web-search, file-write
  Endpoint: http://localhost:3000

rax deploy

Deploy an agent using a provider adapter (local Docker, Fly.io, Railway, Render, Cloud Run, DigitalOcean).

rax deploy up [--target local|fly|railway|render|cloudrun|digitalocean]
              [--mode daemon|sdk]
              [--dry-run]
              [--scaffold-only]
              [--name <agent-name>]

rax deploy down [--target <target>]
rax deploy status [--target <target>]
rax deploy logs [-f] [--target <target>]
rax deploy init   # legacy alias for `deploy up --scaffold-only`

Options:

Option	Default	Description
--target	local (auto-detected if config exists)	Deploy provider adapter
--mode	daemon	daemon for full agent loop, sdk for HTTP API mode
--dry-run	off	Run provider preflight() checks and print execution plan
--scaffold-only	off	Generate config files only, do not deploy
--name	auto-detected from package.json	Agent/app identifier
--follow, -f	off	Follow logs for deploy logs

Provider CLI Contracts:

These commands and flags are validated by apps/cli/tests/cli-contracts.test.ts to detect upstream CLI breaking changes early.

Provider	CLI	Contract Baseline
local	Docker + Compose	Docker >= 20, Compose >= 2, supports compose build/up/down/ps/logs, up -d, logs --tail/--follow, ps --format
fly	flyctl / fly	supports auth whoami, launch --copy-config --name --no-deploy, deploy, status, logs, apps destroy --yes
railway	railway	supports whoami, link, up, down --yes, status, logs, variables
render	render	supports blueprint launch, services list
cloudrun	gcloud	SDK >= 380, supports config get-value project, auth list --filter --format, run deploy --source --region --port --memory --timeout --allow-unauthenticated, run services describe/delete/update
digitalocean	doctl	>= 1.72, supports account get --format --no-header, apps create/list/update/delete/logs, --spec, --format

Containerized CLI fallback:

For flyctl, gcloud, and doctl, rax deploy resolves local binaries first and can fall back to a Docker-wrapped CLI when Docker is available.

Contract test commands:

bun test apps/cli/tests/cli-contracts.test.ts
RUN_SLOW_TESTS=1 bun test apps/cli/tests/cli-contracts.test.ts

RUN_SLOW_TESTS=1 enables container image availability checks for the fallback images.

rax dev

Run your local entrypoint in watch mode.

rax dev [--entry src/index.ts] [--no-watch]

Default entrypoint is src/index.ts. Use --entry if your project uses a different file.

rax eval

Run an evaluation suite from a YAML/JSON dataset file. Uses @reactive-agents/eval with frozen-judge isolation (Rule 4) — the judge LLM is wired through a separate JudgeLLMService Tag so its code path is isolated from the SUT.

rax eval run --suite <path-to-suite> [--provider anthropic|openai|test] [--agent <name>]

Options:

• --suite <path> — required. Path to the suite definition file.
• --provider <name> — anthropic, openai, or test (default: test)
• --agent <name> — agent config name to load from your project (default: default)

The runtime guard rejects identical judge.model === sutModel pairings to prevent self-judging bias.

rax playground

Launch an interactive agent REPL session.

rax playground [--provider <provider>] [--model <model>] [--tools] [--reasoning] [--stream]

Use /help and /exit inside the session.

rax inspect

Inspect local deployment/runtime signals for an agentId.

rax inspect <agent-id> [--logs-tail 200] [--json]

This checks Docker/Compose availability, prints compose status, and scans recent logs for lines containing the provided agentId.

rax diagnose

Forensic CLI for recorded JSONL traces. Subcommands:

rax diagnose list [--limit 20]              # show recent traces
rax diagnose replay <runId> [--raw|--json]  # pretty-print trace timeline
rax diagnose replay-run <runId> [--json]    # recorded-run metadata (replay() API input)
rax diagnose grep <runId> "<js-expr>"       # filter events with a JS predicate
rax diagnose diff <runIdA> <runIdB>         # structural diff between two runs
rax diagnose debrief <runId> [--json]       # decision timeline with rationale

Run IDs accept a bare ULID (resolves under ~/.reactive-agents/traces/), an absolute path to a .jsonl file, or the literal latest. Override the trace directory with REACTIVE_AGENTS_TRACE_DIR.

Snapshot/Replay re-execution is API-only — see Snapshot & Replay for the replay(recordedRun, builderFn) workflow.

The standalone bin rax-diagnose <sub> is kept for backwards compatibility; new code should prefer the unified rax diagnose <sub> form.

rax version

rax version
rax --version
rax -v

rax help

rax help
rax --help
rax -h