Synopsis
Description
pome run is the core loop. It loads a task markdown file — or every .md file
in a directory — boots the twins the task declares, spawns your agent with the
twin URLs injected, records the trace, and scores it against the task’s
acceptance criteria.
Hosted is the default: the run is recorded and scored on app.pome.sh. Pass
--local to run against the in-process twin instead, which captures the trace
but does not score it — evaluation happens in the cloud. To score a trace you
captured that way, run pome eval.
Run the doctor first
pome run runs the pome doctor wiring checks before it spawns
anything, and refuses to start if one fails. There is no --force. The doctor
stops at the first red with one named cause and one fix; apply the fix and run
again.
A hosted run skips the local-twin check — the cloud provisions the twin — and
still gates on the manifest, the routing check, and the egress floor.
Arguments
Options
Plus the global flags —
--api-url, --artifacts-dir, and -V, --version.
-n and --local conflict: trial verdicts are graded in the cloud, so the
combination exits 5 rather than dropping one of the two silently.
Environment variables
Pome injects these into the agent process. Read them instead of hardcoding a host — the difference between a run that grades and one that quietly talked to the real API.Trial groups
-n <count> runs the same task <count> times as one trial group, which is how
you measure whether an agent passes reliably rather than once. Trial groups are
a hosted feature.
Pome mints one sandbox per trial under a shared group id, reusing slots as
trials finish (up to your plan’s concurrent-twin quota), and prints a per-trial
verdict table when the group completes.
The group’s exit code answers one question: did every trial that finished pass?
An incomplete trial leaves the verdict fraction entirely —
2 of 2 passed · 1 incomplete, excluded from the fraction — so it never counts as a pass and is
never charged to the agent as a loss.
Examples
Run what the manifest’stasks field names — or, with no manifest, the demo
task Pome copies in on first use:
command:
Output
Each run writes a directory,<artifacts-dir>/<task>/<run-id>/, holding:
A hosted run adds
verdict.json, the cloud’s verdict for that trial, and prints
a cloud: URL to the dashboard (a trial group prints one group link). A local
run also writes egress.jsonl — refused
hosts, empty when none were. The CLI never writes a score of its own: it
captures, and the cloud grades.
Exit status
pome run returns the worst exit code across every task in the batch. See
the canonical table, and
Trial groups for how a group of trials collapses to one code.
A run the doctor refuses exits 5, the usage-error code: nothing ran, so the
number does not mean the agent scored badly. Read the printed cause.
See also
pome doctor— the checks this command gates on.pome eval— score a trace captured by--local.pome inspect— read the trace in your terminal.pome fix-prompt— turn a failed run set into a prompt for your IDE.