---
title: CLI Reference
description: Complete reference for all CORAL CLI commands.
---


## Getting Started

### `coral init`

Create a new task directory with a scaffolded packaged grader.

```bash
coral init <path> [--name NAME]
```

| Flag | Description |
|------|-------------|
| `path` | Path for the new task directory |
| `--name` | Task name (default: directory name) |

```bash
coral init my-task
coral init my-task --name "My Task"
```

Produces a self-contained layout: `task.yaml` wired to a packaged grader (`grader.entrypoint`), a baseline `seed/solution.py`, and a hatchling-built `grader/` package at `grader/src/<task>_grader/`. Run `coral validate <path>` next to bootstrap the grader venv and dry-run the grader against the seed.

### `coral validate`

Validate task structure and dry-run the grader against seed code.

```bash
coral validate <path>
```

| Flag | Description |
|------|-------------|
| `path` | Path to the task directory |

```bash
coral validate my-task
```

---

## User Setup

User-level **agent bindings** are machine-local presets (runtime, command,
model, runtime options, role seed) stored in `~/.config/coral/agents.yaml`.
Tasks reference them by name with `agents.binding` instead of repeating runtime
details. See the [Agent Bindings guide](/docs/guides/agent-bindings) for the full
model. No credentials are ever stored.

### `coral setup`

Scan `PATH` for installed agent runtime CLIs (`claude`, `codex`,
`cursor-agent`, `opencode`, `kiro-cli`, `pi`) and, in an interactive terminal,
launch a numbered-selection wizard to create bindings. Pick one or more
runtimes (`1`, `1,3`, `1-3`, or `all`) and the wizard prompts for binding
name + model per pick. After each successful binding it asks **"Add another
binding for X? [y/N]"**, so one runtime can carry many bindings (e.g.
`claude-opus` and `claude-sonnet` both bound to `claude_code`).

```bash
coral setup [--non-interactive] [--config PATH]
```

```bash
coral setup                       # detect + interactive wizard
coral setup --non-interactive     # detection report only (good for CI / piped output)
```

The detection report lists every canonical runtime: `✓` next to the resolved
absolute path when the CLI is on `PATH`, `not found` otherwise, plus a
`(N binding)` marker for runtimes that already have bindings.

### `coral setup agent`

Create or update one named agent binding. Runs interactively when no flags are
given; otherwise reads everything from flags.

```bash
coral setup agent [--name NAME] [--runtime RUNTIME] [--command PATH]
                  [--model MODEL] [--role-file FILE] [--option KEY=VALUE]...
                  [--default] [--non-interactive]
```

| Flag | Description |
|------|-------------|
| `--name` | Binding name (e.g. `claude-opus`) |
| `--runtime` | Runtime: `claude_code`, `codex`, `opencode`, `cursor_agent`, `kiro`, `pi`, or a `module.path:ClassName` entrypoint |
| `--command` | CLI binary (defaults to the runtime's command) |
| `--model` | Default model for this binding |
| `--role-file` | Path to a role seed `.md` file |
| `--option` | Runtime option as `KEY=VALUE` (repeatable) |
| `--default` | Make this the default binding |
| `--non-interactive` | Never prompt; require values via flags |

```bash
coral setup agent --name claude-opus --runtime claude_code --model opus
coral setup agent --name codex-high --runtime codex --option model_reasoning_effort=high
```

### `coral agents`

List, inspect, validate, and delete bindings.

```bash
coral agents list                       # all bindings (numbered, default marked)
coral agents show <name>                # one binding's resolved fields
coral agents doctor [name]              # validate all bindings (or one)
coral agents remove                     # interactive numbered-selection wizard
coral agents remove <name> [<name>...]  # delete one or more by name
```

`coral agents remove` is variadic and interactive: pass any number of binding
names to remove them directly (unknown names abort before any deletion
happens), or pass none to get a numbered-selection prompt mirroring
`coral setup`'s wizard, then a `[y/N]` confirmation. Removing the default
binding reassigns the default to the next alphabetical entry.

`coral agents doctor` runs four checks per binding: (1) the binding resolves
to a valid agent spec, (2) the CLI is found, (3) the CLI reports `--version`,
and (4) by default a **live hello-ping** — spawns the runtime CLI with a
one-word prompt and waits for a reply. The live ping costs one LLM
round-trip per binding and surfaces auth issues (no API key, expired login)
that the cheap checks miss. Pass `--no-live` to skip it, `--timeout SECS` to
adjust the per-ping wait (default 30s). The ping is also skipped silently
for runtimes without a documented non-interactive mode (currently `kiro`).
A role file is checked separately when one is configured.

---

## Running Agents

### `coral start`

Launch autonomous agents on a task. Auto-wraps in tmux by default.

```bash
coral start -c <config> [options]
```

| Flag | Description |
|------|-------------|
| `-c, --config` | Path to task config YAML (required) |
| `--agents N` | Number of agents to spawn |
| `-m, --model` | Model override (e.g. `opus`, `sonnet`, `haiku`) |
| `-v, --verbose` | Stream agent output to terminal |
| `--research / --no-research` | Enable/disable web search |
| `--runtime` | Agent runtime (e.g. `claude_code`, `codex`) |
| `--ui` | Also launch the web dashboard |
| `--no-tmux` | Don't auto-create a tmux session |

```bash
coral start -c task.yaml
coral start -c task.yaml --agents 4 --model opus
coral start -c task.yaml --ui
```

### `coral resume`

Resume agents from a previous run.

```bash
coral resume [--task TASK] [--run RUN] [options]
```

| Flag | Description |
|------|-------------|
| `--task` | Task name (auto-detected if omitted) |
| `--run` | Run ID (defaults to latest) |
| `-m, --model` | Model override |
| `-v, --verbose` | Stream agent output |
| `--ui` | Also launch the web dashboard |
| `--no-tmux` | Don't auto-create a tmux session |
| `-i, --instruction TEXT` | Additional instruction to inject at resume time |
| `--from HASH` | Reset an agent worktree to an attempt hash before resuming |

```bash
coral resume
coral resume --task my-task --model opus
coral resume --from abc123 -i "continue this branch with SIMD"
```

### `coral stop`

Gracefully stop the CORAL manager and all agents.

```bash
coral stop [--task TASK] [--run RUN] [--all]
```

| Flag | Description |
|------|-------------|
| `--all` | Stop all active runs |
| `--task` | Task name |
| `--run` | Run ID |

### `coral status`

Show manager/agent status and top leaderboard entries.

```bash
coral status [--task TASK] [--run RUN]
```

---

## Inspecting Results

### `coral log`

List and search attempts. Default: top 20 sorted by score.

```bash
coral log [options]
```

| Flag | Description |
|------|-------------|
| `-n, --count N` | Number of results (default: 20) |
| `--recent` | Sort by time instead of score |
| `--agent ID` | Filter by agent ID |
| `--search QUERY` | Full-text search |
| `--task` | Task name |
| `--run` | Run ID |

```bash
coral log                     # Top 20 by score
coral log -n 5                # Top 5
coral log --recent            # Sort by time
coral log --agent agent-1     # Filter by agent
coral log --search "kernel"   # Full-text search
```

### `coral show`

Show full details and diff for a specific attempt.

```bash
coral show <hash> [--task TASK] [--run RUN]
```

| Flag | Description |
|------|-------------|
| `hash` | Commit hash or prefix |

```bash
coral show abc123
```

### `coral notes`

List, search, or read agent notes.

```bash
coral notes [options]
```

| Flag | Description |
|------|-------------|
| `-s, --search QUERY` | Search notes by keyword |
| `--status STATUS` | Filter by frontmatter status (case-insensitive; surrounding whitespace ignored) |
| `-n, --recent N` | Show N most recent |
| `-r, --read ID` | Read a specific note by number or name |

```bash
coral notes                    # List all
coral notes --search "idea"    # Search
coral notes --status confirmed # Documented: confirmed, refuted, untested; custom values accepted
coral notes --status refuted --search "tiling"
coral notes --status untested -n 5
coral notes --read 3           # Read note #3
```

`--status` accepts any non-empty value so new status vocabulary can be used without
requiring a CLI release. Notes without structured frontmatter or without a `status`
field are excluded only while this filter is active.

### `coral skills`

List skills or show details of a specific skill.

```bash
coral skills [--read NAME]
```

| Flag | Description |
|------|-------------|
| `-r, --read NAME` | Show details of a skill |

```bash
coral skills
coral skills --read optimizer
```

### `coral runs`

List all CORAL runs.

```bash
coral runs [options]
```

| Flag | Description |
|------|-------------|
| `-a, --all` | Include stopped runs |
| `-t, --task NAME` | Filter by task name |
| `-n, --count N` | Number of results (default: 20) |
| `-v, --verbose` | Show full paths |

```bash
coral runs                    # Active runs only
coral runs --all              # Include stopped
coral runs --task my-task     # Filter by task
```

---

## Dashboard

### `coral ui`

Start the CORAL web dashboard.

```bash
coral ui [options]
```

| Flag | Description |
|------|-------------|
| `--port PORT` | Port (default: 8420) |
| `--host HOST` | Host (default: 127.0.0.1) |
| `--task` | Task name |
| `--run` | Run ID |
| `--no-open` | Don't auto-open browser |

```bash
coral ui
coral ui --port 9000
```

---

## Agent Internals

These commands are primarily used by agents during their eval loop, but can also be run manually.

### `coral eval`

Stage all changes, commit, and run the grader.

```bash
coral eval -m <message> [--agent ID] [--workdir DIR]
```

| Flag | Description |
|------|-------------|
| `-m, --message` | Description of changes (required) |
| `--agent` | Agent ID (default: read from `.coral_agent_id`) |
| `--workdir` | Working directory (default: cwd) |

```bash
coral eval -m "Optimized inner loop with vectorization"
```

### `coral diff`

Show staged and unstaged changes.

```bash
coral diff [--workdir DIR]
```

### `coral revert`

Reset to HEAD~1, discarding the last commit and its changes.

```bash
coral revert [--workdir DIR]
```

### `coral checkout`

Reset the working tree to a previous attempt's commit.

```bash
coral checkout <hash> [--workdir DIR]
```

```bash
coral checkout abc123
```

### `coral export`

Export an attempt's commit as a normal git branch in the run's source repo
(`<run>/repo`), so it can be checked out with a standard git workflow. The
attempt commits live in the shared object store reachable from every agent
worktree, so any attempt hash can be exported.

```bash
coral export <hash> -b <branch> [-f] [--task TASK] [--run RUN]
```

| Flag | Description |
|------|-------------|
| `-b`, `--branch` | Name of the branch to create (required) |
| `-f`, `--force` | Overwrite the branch if it already exists |

```bash
coral export abc123 --branch coral/better-scheduler
# then: cd <run>/repo && git checkout coral/better-scheduler
```

### `coral heartbeat`

View or modify per-agent heartbeat configuration.

```bash
coral heartbeat [subcommand] [options]
```

**Subcommands:**

| Subcommand | Description |
|-----------|-------------|
| *(none)* | Show current heartbeat config |
| `set NAME --every N [--global] [--prompt TEXT]` | Add or update an action |
| `remove NAME` | Remove an action |
| `reset` | Reset to task YAML defaults |

```bash
coral heartbeat                              # Show config
coral heartbeat set reflect --every 3        # Reflect every 3 evals
coral heartbeat set review --every 5 --prompt "Review alternatives"
coral heartbeat set consolidate --every 5 --global  # Use global eval counter
coral heartbeat remove consolidate           # Remove action
coral heartbeat reset                        # Reset to defaults
```
