> ## 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 session

> Create, list, and stop hosted sandbox sessions for GitHub and Stripe twins.

`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

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

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

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

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

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

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

```bash theme={"dark"}
pome session stop ses_abc123 --discard
```