CLI Reference

Getting Started

coral init

Create a new task directory with a scaffolded packaged grader.

coral init <path> [--name NAME]

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.

coral validate <path>

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

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

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.

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

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.

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.

coral start -c <config> [options]

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.

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

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.

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

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]

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.

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

coral show abc123

coral notes

List, search, or read agent notes.

coral notes [options]

coral notes                    # List all
coral notes --search "idea"    # Search
coral notes --read 3           # Read note #3

coral skills

List skills or show details of a specific skill.

coral skills [--read NAME]

coral skills
coral skills --read optimizer

coral runs

List all CORAL runs.

coral runs [options]

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.

coral ui [options]

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.

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

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

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

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.

coral heartbeat [subcommand] [options]

Subcommands:

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