CLI Reference
Complete reference for all CORAL CLI commands.
Getting Started
coral init
Create a new task directory with scaffolded config and grader.
coral init <path> [--name NAME]| Flag | Description |
|---|---|
path | Path for the new task directory |
--name | Task name (default: directory name) |
coral init my-task
coral init my-task --name "My Task"coral validate
Validate task structure and dry-run the grader against seed code.
coral validate <path>| Flag | Description |
|---|---|
path | Path to the task directory |
coral validate my-taskRunning Agents
coral start
Launch autonomous agents on a task. Auto-wraps in tmux by default.
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 |
coral start -c task.yaml
coral start -c task.yaml --agents 4 --model opus
coral start -c task.yaml --uicoral resume
Resume agents from a previous run.
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 |
coral resume
coral resume --task my-task --model opuscoral stop
Gracefully stop the CORAL manager and all agents.
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.
coral status [--task TASK] [--run RUN]Inspecting Results
coral log
List and search attempts. Default: top 20 sorted by score.
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 |
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 searchcoral show
Show full details and diff for a specific attempt.
coral show <hash> [--task TASK] [--run RUN]| Flag | Description |
|---|---|
hash | Commit hash or prefix |
coral show abc123coral notes
List, search, or read agent notes.
coral notes [options]| Flag | Description |
|---|---|
-s, --search QUERY | Search notes by keyword |
-n, --recent N | Show N most recent |
-r, --read ID | Read a specific note by number or name |
coral notes # List all
coral notes --search "idea" # Search
coral notes --read 3 # Read note #3coral skills
List skills or show details of a specific skill.
coral skills [--read NAME]| Flag | Description |
|---|---|
-r, --read NAME | Show details of a skill |
coral skills
coral skills --read optimizercoral runs
List all CORAL runs.
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 |
coral runs # Active runs only
coral runs --all # Include stopped
coral runs --task my-task # Filter by taskDashboard
coral ui
Start the CORAL web dashboard.
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 |
coral ui
coral ui --port 9000Agent 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.
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) |
coral eval -m "Optimized inner loop with vectorization"coral diff
Show staged and unstaged changes.
coral diff [--workdir DIR]coral revert
Reset to HEAD~1, discarding the last commit and its changes.
coral revert [--workdir DIR]coral checkout
Reset the working tree to a previous attempt's commit.
coral checkout <hash> [--workdir DIR]coral checkout abc123coral heartbeat
View or modify per-agent heartbeat configuration.
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 |
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