pome run

pome run is the core workflow: it loads a task markdown file (or every .md in a directory), boots the matching twin, spawns your agent with injected environment variables, records the trace, and scores the result against the acceptance criteria. Hosted is the default — runs are recorded and scored on app.pome.sh. Use pome run --local to run against the in-process local twin (GitHub, Stripe, or Slack depending on the task): it records the trace but does not score — evaluation is a hosted feature.

Usage

pome run <path> [options]

Arguments

Argument	Required	Description
`<path>`	Yes	Path to a task `.md` file or a directory. Directories run every `.md` file inside, in sorted order.

Options

Flag	Default	Description
`--agent <command>`	`pome.config.json` → `examples/agents/scripted-triage-agent.ts`	Shell command Pome spawns as the agent process.
`--artifacts-dir <dir>`	`runs`	Where to write per-run artifacts (`events.jsonl`, `score.json`, state snapshots).
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL for hosted runs.
`--agent-model <name>`	`unknown`	Informational model name recorded on the cloud run.
`--no-fix-prompt`	off	Skip CLI-side LLM fix-prompt generation. Submits `fix_prompt: null` to save tokens on bulk runs.
`--no-capture`	off	Self-host only. Skip the capture-server child and do not inject `HTTP_PROXY` / `HTTPS_PROXY` into the agent. No-op on hosted runs.
`--local`	off	Self-host, no scoring. Run against an in-process twin and record the trace + state, but skip evaluation — no `score.json`, no pass/fail verdict. Evaluation is a hosted feature; `pome login` and re-run to score on Pome cloud.
`--hosted`	—	Deprecated no-op. Hosted is now the default. Kept for one release so existing scripts do not break.

Environment variables

Pome injects these into the agent process during a run:

Variable	When
`POME_TASK`	Always. The task prompt from `## Prompt`.
`POME_<TWIN>_REST_URL`	Always. Session-scoped REST root (`GITHUB`, `STRIPE`, or `SLACK`).
`POME_<TWIN>_MCP_URL`	Always. MCP transport endpoint for the active twin.
`POME_AUTH_TOKEN`	Always. Short-lived JWT for twin session auth.
`POME_RUN_ID`	Always. Unique run identifier.
`POME_ARTIFACTS_DIR`	Always. Per-run artifact directory path.
`POME_ADAPTER_SIGNALS_PATH`	When the agent adapter writes supplemental signals.
`HTTP_PROXY` / `HTTPS_PROXY`	Hosted and local capture-on runs. Agent outbound traffic flows through the capture-server.
`NO_PROXY`	Set to `127.0.0.1,localhost` so twin traffic stays in-process.
`POME_PREFLIGHT=1`	During agent preflight. Your agent should exit 0 immediately without doing work.

For hosted Stripe runs, Pome may also set POME_STRIPE_API_BASE and POME_STRIPE_API_KEY instead of the generic twin URL pattern. Use pome run --local to run against the local in-process twin and skip hosted auth — it records a trace but does not score (evaluation is a hosted feature). POME_LOCAL=1 is the internal escape hatch that runs locally and scores (used by pome matrix).

Examples

# Single task (hosted default)
pome run tasks/01-bug-happy-path.md

# Custom agent command
pome run tasks/10-stripe-create-payment-intent.md \
  --agent "npx tsx examples/agents/llm-refund-agent.ts"

# Run every task in a directory
pome run tasks/ --agent "node ./dist/agent.js"

# Self-host: local in-process twin, trace captured but NOT scored
pome run --local tasks/20-slack-exfiltration.md

# Bulk run without fix-prompt LLM calls
pome run tasks/ --no-fix-prompt

Output

Each run writes artifacts under runs/<task>/<run-id>/:

events.jsonl — canonical event stream (TwinHttpEvent, LlmCallEvent, etc.)
score.json — per-criterion verdicts and aggregate satisfaction score. Not written for --local runs (evaluation is hosted; --local captures the trace only).
state_initial.json / state_final.json — twin state before and after the agent

Hosted runs also print a cloud: URL to the dashboard.

Exit codes

Returns the worst exit code across all tasks in a batch. See CLI overview — exit codes.

Start

Guides

CLI

MCP

Usage

Arguments

Options

Environment variables

Examples

Output

Exit codes

​Usage

​Arguments

​Options

​Environment variables

​Examples

​Output

​Exit codes

Usage

Arguments

Options

Environment variables

Examples

Output

Exit codes