pome CLI commands: run, inspect, export, and more

pome init

Scaffold a new Pome project in the current directory. Running pome init creates a .pome.json config file, a harness.ts (or harness.py) entrypoint, and a scenarios/ directory with one example scenario.Synopsis

pome init [--mode oss|hosted] [--language ts|python]

Flags

Flag	Description
`--mode oss\|hosted`	Set the deployment mode. Defaults to `oss`.
`--language ts\|python`	Language for the generated harness file. The CLI auto-detects from the project if omitted.
`--force`	Overwrite an existing `.pome.json`. Without this flag, `pome init` exits with code `1` if the file already exists.

Exit codes

Code	Meaning
`0`	Project scaffolded successfully
`1`	`.pome.json` already exists — re-run with `--force` to overwrite

Example

# Scaffold a TypeScript project in hosted mode
pome init --mode hosted --language ts

pome login

Authenticate with the hosted Pome control plane. By default, pome login starts a local HTTP callback server and opens your browser to https://pome.sh/cli-auth. After you complete the OAuth flow, credentials are written to ~/.pome/credentials.json.Synopsis

pome login [--token <api-key>]

Flags

Flag	Description
`--token <api-key>`	Skip the OAuth browser flow and write the provided API key directly. Use this in CI environments where a browser is unavailable.

Exit codes

Code	Meaning
`0`	Authenticated successfully
`2`	User cancelled the browser OAuth flow

Example

# Authenticate via browser (interactive)
pome login

# Authenticate with an API key in CI
pome login --token pme_yourteamkey

In CI pipelines, prefer setting the POME_API_KEY environment variable instead of running pome login. The CLI reads POME_API_KEY automatically and never writes a credentials file. See environment variables for details.

pome logout

Remove stored credentials. pome logout deletes ~/.pome/credentials.json and attempts a best-effort token revocation server-side. If the revocation request fails (e.g., no network), the local credentials are still removed.Synopsis

pome logout

Exit codes

Code	Meaning
`0`	Credentials removed

Example

pome logout

pome run

Run one or more scenarios against a twin. This is the primary command in the Pome workflow. pome run boots a twin, sets POME_* environment variables, launches your agent process as a child, records every tool call, evaluates the final twin state against your scenario’s success criteria, and writes run artifacts to disk.Synopsis

pome run <scenario.md|dir>
         [--runs <N>]
         [--timeout <seconds>]
         [--seed <name|path>]
         [--harness <path>]
         [--tag <tag>]
         [--pass-threshold <0-100>]
         [--reuse-session <id>]

Arguments

Argument	Description
`<scenario.md\|dir>`	Path to a single scenario file or a directory of scenario files. When a directory is given, all `.md` files inside are run in order.

Flags

Flag	Description
`--runs <N>`	Number of times to run each scenario. Useful for measuring pass-rate consistency across multiple runs.
`--timeout <seconds>`	Maximum wall-clock time allowed for each scenario run. The twin and agent process are killed if the timeout is reached.
`--seed <name\|path>`	Named seed or path to a seed JSON file to apply to the twin before the run. Overrides the `## Seed State` section in the scenario file.
`--harness <path>`	Path to the harness file. Overrides the value in `.pome.json`.
`--tag <tag>`	Attach a tag to the run for filtering in the dashboard or `pome sessions list`.
`--pass-threshold <0-100>`	Minimum satisfaction score (0–100) required for a scenario to count as passing. Default is `0`. Exit code `1` is returned if any scenario falls below this threshold.
`--reuse-session <id>`	Attach to an existing hosted session instead of provisioning a new one. Useful for debugging a specific session state.

Exit codes

Code	Meaning
`0`	All scenarios met `--pass-threshold`
`1`	One or more scenarios fell below `--pass-threshold`
`2`	Twin or orchestrator error (boot failure, connectivity issue)
`3`	Authentication error — run `pome login` or set `POME_API_KEY`
`4`	Quota exceeded — check your plan or run `pome sessions list`
`5`	Usage error — bad flags, missing files, or malformed scenario

Examples

# Run all scenarios in the scenarios/ directory
pome run scenarios/

# Run a single scenario with a 60-second timeout and 100% pass threshold
pome run scenarios/01-bug-happy-path.md --timeout 60 --pass-threshold 100

# Run three times and require all runs to pass
pome run scenarios/ --runs 3 --pass-threshold 100

# Use a custom seed file
pome run scenarios/01-bug-happy-path.md --seed seeds/fresh-repo.json

Run artifacts are written to runs/<scenario-name>/<run-id>/ and include tool_calls.jsonl, state_initial.json, state_final.json, and score.json. Use pome inspect latest to view results immediately after a run.

pome inspect

Pretty-print a run’s full trace. In OSS mode, pome inspect reads artifacts from the local runs/ directory. In hosted mode, it fetches run metadata and downloads blobs from signed S3 URLs.Synopsis

pome inspect <run-id> [--format json|terminal]
pome inspect latest

Arguments

Argument	Description
`<run-id>`	The run ID to inspect (e.g., `run_aB3kPq`).
`latest`	Shorthand for the most recent run in the current project.

Flags

Flag	Description
`--format json\|terminal`	Output format. `terminal` (default) renders a human-readable trace with pass/fail indicators per criterion. `json` emits the raw run record.

Example

# Inspect the most recent run
pome inspect latest

# Inspect a specific run in JSON format
pome inspect run_aB3kPq --format json

Example terminal output:

Score: 100/100
✓ [D] Issue #1 has the `bug` label applied
✓ [D] Issue #1 is assigned to `alice`
✓ [D] No unsupported endpoint was called

pome export

Export a run as a .tar.gz archive. The archive is useful for filing support tickets, sharing run artifacts with teammates, or performing offline replay analysis.Synopsis

pome export <run-id>

Archive contents

File	Description
`meta.json`	Run metadata — scenario name, duration, agent model, satisfaction score
`tool_calls.jsonl`	Every HTTP call the agent made to the twin, with request and response bodies
`state_initial.json`	Full twin state at the start of the run
`state_final.json`	Full twin state after the agent finished
`score.json`	Per-criterion evaluation results

Example

pome export run_aB3kPq
# Writes run_aB3kPq.tar.gz to the current directory

pome twin

Boot a standalone twin in the foreground for manual exploration and debugging. This is primarily useful in self-hosted (OSS) mode when you want to poke at the twin’s API directly without running a full scenario.Synopsis

pome twin [--port 3000] [--seed <path>]
pome twin reset

Subcommands

Subcommand	Description
(no subcommand)	Boot the twin in the foreground. Press Ctrl+C to stop.
`reset`	Reset the running twin’s state back to its default seed without restarting the process.

Flags

Flag	Description
`--port <number>`	Port to listen on. Defaults to `3000`.
`--seed <path>`	Path to a seed JSON file to apply on boot.

Example

# Start the twin on the default port
pome twin

# In another terminal, poke the GitHub REST surface
curl http://127.0.0.1:3000/repos/acme/api/issues/1

# Try an unsupported endpoint — expect a loud 501, not a silent 404
curl http://127.0.0.1:3000/repos/acme/api/pulls

# Reset state without restarting
pome twin reset

pome sessions

List or kill active hosted sessions. Use this to debug quota usage, inspect session state, or manually tear down sessions that are no longer needed.Synopsis

pome sessions list
pome sessions kill <session-id>
pome sessions kill --all

Subcommands

Subcommand	Description
`list`	List all active sessions for your team, with their IDs, state, and expiry times.
`kill <session-id>`	Tear down a specific session early.
`kill --all`	Tear down all active sessions for your team.

Example

# List active sessions
pome sessions list

# Kill a specific session
pome sessions kill ses_aB3kPq

# Kill everything (useful when you've hit your session quota)
pome sessions kill --all

pome version

Print the current CLI version. If a newer release is available, pome version prints the latest version on a second line so you know to upgrade.Synopsis

pome version

Example

pome 1.4.2
Latest: 1.5.0 — run `npm install -g pome` to upgrade

Get Started

Core Concepts

Guides

CLI Reference

Plans & Pricing

pome CLI commands: run, inspect, export, and more

Get Started

Core Concepts

Guides

CLI Reference

Plans & Pricing

Documentation Index