> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pome.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# pome run

> Run task files against a twin, record tool calls, and score the agent.

`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

```bash theme={"dark"}
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

```bash theme={"dark"}
# 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](./index#exit-codes).