pome session

pome session manages hosted twin sandboxes on the Pome control plane—the same sessions you see on the dashboard Twins page. It requires pome login (or POME_API_KEY). GitHub and Stripe are supported today. Slack is local pome run only.

Usage

pome session create [options]
pome session list [options]
pome session stop <session-id> [options]
pome session kill <session-id>   # alias for stop

`session create`

Spin up a hosted sandbox for a twin and print connection details.

Options

Flag	Default	Description
`--twin <name>`	—	Required. `github` or `stripe`.
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.
`--show-secrets`	off	Print bearer tokens and API keys. Unsafe on shared terminals.
`--format <fmt>`	`text`	Output format: `text`, `json`, or `env` (shell `export` lines).

Examples

pome session create --twin github
pome session create --twin stripe --format env
pome session create --twin github --show-secrets --format json

With --format env, output includes lines like:

export POME_GITHUB_REST_URL=...
export POME_AUTH_TOKEN=...
export POME_STRIPE_API_KEY=...    # stripe sessions only

`session list`

List hosted sessions. Defaults to --state running, matching the dashboard view.

Options

Flag	Default	Description
`--state <state>`	`running`	Filter: `running`, `ready`, `done`, `expired`, or `all`. `running` matches both server-side `ready` and `running`.
`--limit <n>`	`20`	Maximum rows to return.
`--format <fmt>`	`text`	`text` or `json`.
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.

Examples

pome session list
pome session list --state all --limit 50
pome session list --format json

`session stop`

Stop a hosted session by id (ses_…). Pome creates the run row at finalize, so a still-open session’s run has not been graded yet — stopping it without confirming would silently discard that run. An unconfirmed stop of an open session is refused, naming the task, how long it’s been open, and telling you to pass --discard to confirm.

Arguments

Argument	Required	Description
`<session-id>`	Yes	Session id from `session create` or `session list`.

Options

Flag	Default	Description
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.
`--discard`	off	Confirm you mean to destroy a session whose run has not been graded.

Examples

pome session stop ses_abc123
pome session kill ses_abc123   # same as stop

A stop on a still-open session is refused rather than run:

Refused to stop ses_abc123: it is still open (running), so its run has not
been graded — Pome creates the run row at finalize, and stopping now
discards it.
  Task: my-task
  Open for 42s.
  To keep the run, finalize it instead. To discard it anyway:
  pome session stop ses_abc123 --discard

To keep the run, finalize the session instead (via the MCP finalize_run tool, or whatever finalized the run in your flow) — finalizing grades the run and flips the session to done, so no session stop is needed after. To discard the run anyway, re-run with --discard:

pome session stop ses_abc123 --discard

Start

Guides

CLI

MCP

pome session

Usage

`session create`

Options

Examples

`session list`

Options

Examples

`session stop`

Arguments

Options

Examples

​Usage

​session create

​Options

​Examples

​session list

​Options

​Examples

​session stop

​Arguments

​Options

​Examples

Usage

`session create`

Options

Examples

`session list`

Options

Examples

`session stop`

Arguments

Options

Examples