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

# heymcp sessions

> List your recent sessions.

```bash theme={null}
heymcp sessions
```

Column-aligned rows of your recent tunnels — which are live, which have closed,
and which have aged out of your retention window.

Useful for two things in particular: finding a session id to
[export](/cli/export), and seeing what's holding your concurrent tunnel slots
when a `heymcp share` gets refused.

## Reading the output

Each row shows the session's status, its slug, when it opened, and its activity.

| Status    | Meaning                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------- |
| `live`    | Connected right now.                                                                               |
| `closed`  | Finished. History still readable.                                                                  |
| `expired` | Past your [retention window](/concepts/sessions#retention) — the row remains, the events are gone. |

## Scripting

```bash theme={null}
heymcp sessions --json
```

Emits `{"sessions": [...]}`. It exits `0` whether or not there are any — with
none, the human-readable form prints *"no sessions yet"* instead of a table.

```bash theme={null}
heymcp sessions --json | jq -r '.sessions[0].id'
```

## Related

* [`heymcp export`](/cli/export) — take a session's history with you
* [Sessions and history](/concepts/sessions) — what the states mean and how long
  things live