Skip to main content

​
Description

The pome CLI runs your agent against deterministic digital twins, records every tool call it makes, and gets the trace scored. Hosted runs record and score on app.pome.sh, and that is the default. pome run --local boots an in-process twin and captures the trace without scoring it; to get a verdict on a captured trace, run pome eval. Every command below has its own reference page. Each page follows the same order — synopsis, description, arguments, options, examples, exit status, see also — so you can skip to the section you came for.

​
Install the CLI

Node 24 or newer (the package declares engines.node >= 24). Every command on these pages is spelled pome … and assumes a global install. npx or -g, and why the walkthroughs differ from this page. The walkthroughs on this site run npx @pome-sh/cli@latest <command> so a reader can type one command without installing anything, pinned to @latest per invocation. Install globally the moment you run pome more than once — npx re-resolves the package every time. The two are the same binary: same commands, same flags, same exit codes, and pome login stores its credentials in the same place either way.

​
Command index

​
Set up and check

​
Run and read

​
Author tasks

​
Twins

​
Auth and utilities

One shipped command has no page on purpose. pome capture-server boots the proxy that records your agent’s model calls, and pome run spawns it for you; run it by hand only when you are debugging the proxy itself.
The coach skills are installed by the skills CLI and talk to Pome over MCP:
--skill '*' takes all six coach skills in one pass; without it the installer opens a checklist with nothing ticked. Then add https://mcp.pome.sh/mcp to your coding agent as a remote HTTP MCP server — Connect to the MCP has the wiring for each client. See the graded capstone for the full walkthrough.

​
Auth resolution order

Hosted commands look for a team API key in this order and stop at the first hit:
  1. The POME_API_KEY environment variable.
  2. The macOS Keychain entry (security find-generic-password -s sh.pome.cli), on macOS.
  3. ~/.pome/credentials.json, written by pome login.
With none of the three set, hosted commands refuse to run rather than running unauthenticated; pome run and pome eval fail fast on exit code 3. pome run --local works with no credentials: it boots a local in-process twin and captures the trace. It does not score — exit 0 means “trace captured”, not “task passed”. Send the trace to pome eval — which does need credentials — to get a verdict on it.

​
Global flags

--api-url and --artifacts-dir are declared on pome itself, so every subcommand accepts them — including the local-only ones (pome doctor, pome logout, pome twin status, pome init, pome docs), where they are accepted and inert. They parse wherever you already write them — after the subcommand, after the positional arguments — so nothing spelled the old way needs to move. The only visible change is in --help: pome <command> --help lists them in a trailing Global Options: block rather than in that command’s own Options: list, and -V, --version sits in that block too.

​
Exit status

Every command returns one of these codes. Pages that add a code of their own say so and link back here. A --local run is not scored, so its exit code reports only whether the agent ran cleanly (0) or errored (2). Exit 0 from --local means “trace captured”, not “task passed” — do not gate CI on it.

​
INCOMPLETE also exits 1

A run whose criteria could not all be graded is INCOMPLETE: not a pass, and not the agent’s failure either — the gap is in the grading, not in the answer. pome run exits 1 on it rather than mapping the partial score straight to an exit code, because a run whose checks never ran is not a green CI signal. The cost, stated plainly: exit 1 cannot tell “the agent regressed” from “we could not grade it”. To tell them apart, read the printed verdict word — INCOMPLETE against a sub-threshold score — or open the run URL, where the score names its denominator (3 of 3 criteria passed · 1 not evaluated). A trial group (pome run -n k, where k is above 1) maps the same way: 0 only when every completed trial passed, 1 when a completed trial failed or was incomplete, 2 when no trial completed. An incomplete trial is excluded from the verdict fraction — 3 of 4 passed · 1 incomplete — so it never counts as a pass and is never charged to the agent as a loss.

​
See also