---
title: CLI Reference
description: 'Command reference for Rax, the CLI for Reactive Agents.'
---

`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](/guides/cli-artisan/).

## Commands

### `rax init`

Create a new Reactive Agents project.

```bash
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.

```bash
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`, `gemini`, `groq`, `xai`, or `ollama` (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.

```bash
$ rax create agent my-agent --interactive

Create Agent (Interactive)
? Agent name: my-research-agent
? Provider [anthropic/openai/gemini/groq/xai/ollama]: 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.

```bash
rax run <prompt> [--provider anthropic|openai|gemini|groq|xai|ollama|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:**

```bash
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):**
```bash
bun add @reactive-agents/cortex
rax cortex
# Opens http://127.0.0.1:4321 in your browser
```

**From source (for contributors with hot reload):**
```bash
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:

```bash
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.

```bash
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:**

```bash
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.

```bash
rax discover <url>
```

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

**Example:**

```bash
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).

```bash
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:**

```bash
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.

```bash
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.

```bash
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.

```bash
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`.

```bash
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:

```bash
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](/features/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`

```bash
rax version
rax --version
rax -v
```

### `rax help`

```bash
rax help
rax --help
rax -h
```
