Command Line Interface

The pome CLI runs agent tasks against deterministic twins, records every tool call, and scores the results. Hosted runs record and score on app.pome.sh by default; pome run --local runs the in-process twin and records the trace without scoring (evaluation is a hosted feature).

Command index

Command	What it does	Reference
`pome run`	Run one or more task files against a twin and score the agent.	run
`pome session`	Create, list, and stop hosted sandbox sessions.	session
`pome tasks`	Browse and copy the bundled task library.	tasks
`pome compile-seeds`	Compile prose seed sections into `.seed.json` sidecars.	compile-seeds
`pome inspect`	Print a human-readable report for a run.	inspect
`pome init`	Scaffold `tasks/`, `examples/agents/`, and `pome.config.json`.	init

Other commands

Command	What it does
`pome login` / `pome logout`	Sign in via browser and store a team API key; clear local credentials.
`pome register agent <name>`	Create a cloud agent and write `agentId` + `agentSlug` to `pome.config.json`.
`pome doctor`	Check the agent↔twin wiring — config valid, twin boots, requests routed to the twin, egress floor active. Prints one named cause and one fix at the first failure.
`pome eval <run-dir>`	Upload an already-captured trace directory for cloud evaluation and print the authoritative score.
`pome demo`	Zero-auth first run: boots a local GitHub twin, runs the bundled demo agent for 5 trials, ends with a no-login preview link.
`pome docs [topic]`	Read bundled docs in the terminal or print `docs.pome.sh` URLs.
`pome install`	Retired. Prints the Gen-2 wiring path instead of running anything.
`pome twin start <name>`	Start a standalone GitHub twin on a local port.
`pome twin reset` / `pome twin status`	Reset or inspect standalone twin state.
`pome twin endpoints <name>`	List the endpoints a twin supports.
`pome fix-prompt`	Generate a paste-into-IDE fix prompt for a failed run (BYOK LLM).
`pome health`	In-process smoke check against the bundled GitHub twin.
`pome version`	Print the CLI version.

The CLI no longer installs agent skills. The coach skills are installed by the skills CLI and talk to Pome over MCP:

claude mcp add --transport http pome https://mcp.pome.sh/mcp
npx skills add pome-sh/digital-twins

That is what pome install prints. See the Quickstart for the full walkthrough.

Auth resolution order

POME_API_KEY environment variable.
macOS Keychain entry (security find-generic-password -s pome-sh) on macOS.
~/.pome/credentials.json written by pome login.

If none are set, hosted commands fail fast. Use pome run --local to bypass auth and run against a local in-process twin (trace only, no scoring).

Exit codes

Stage 1 known regressions: some pome run paths return exit code 2 or 3 when 1 was documented. CI consumers branching on $? should not yet treat this table as a hard contract. See troubleshooting.

A --local run is not scored, so its exit code reflects only whether the agent ran cleanly (0) or errored/timed out (3) — exit 0 from --local means “trace captured,” not “task passed.” Do not gate CI on a --local exit code.

Code	Meaning
0	All tasks passed (hosted/scored run), or trace captured (`--local`, not scored).
1	At least one task scored below threshold.
2	Twin or runner error (network, 5xx, twin spawn failed).
3	Auth error (401/403). Re-run `pome login`.
4	Quota exceeded.
5	Usage error (bad flags, missing files).

​Command index

​Other commands

​Auth resolution order

​Exit codes

Command index

Other commands

Auth resolution order

Exit codes