# Session CLI Reference

The `agents session` command group manages **sessions** — persistent conversation threads tied to orchestrator actors.

## Commands

| Command | Description |
|---------|-------------|
| `agents session create` | Create a new interactive session |
| `agents session list` | List all sessions |
| `agents session show` | Show session details and recent messages |
| `agents session delete` | Delete a session permanently |
| `agents session export` | Export a session as JSON |
| `agents session import` | Import a session from JSON |
| `agents session tell` | Send a message to a session |

---

## `agents session create`

Create a new interactive session, optionally bound to an orchestrator actor.

```bash
agents session create [--actor <ACTOR>] [--format <FORMAT>]
```

### Options

| Flag | Description |
|------|-------------|
| `--actor` | Orchestrator actor name in `namespace/name` format |
| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` (default: `rich`) |

### Output

Returns session info including `session_id`, `actor`, `created`, and `namespace`.

### Example

```bash
agents session create --actor openai/gpt-4
agents session create --format json
```

---

## `agents session list`

List all sessions with message counts and timestamps.

```bash
agents session list [--format <FORMAT>]
```

### Options

| Flag | Description |
|------|-------------|
| `--format`, `-f` | Output format (default: `rich`) |

### JSON Output Shape

```json
{
  "sessions": [
    {"id": "...", "actor": "...", "messages": 5, "updated": "..."}
  ],
  "total": 1
}
```

---

## `agents session show`

Show session details including recent messages, linked plans, and token usage.

```bash
agents session show <SESSION_ID> [--format <FORMAT>]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `SESSION_ID` | The ULID of the session to display |

### Options

| Flag | Description |
|------|-------------|
| `--format`, `-f` | Output format (default: `rich`) |

---

## `agents session delete`

Delete a session permanently. A confirmation prompt is shown unless `--yes` is provided.

```bash
agents session delete <SESSION_ID> [--yes]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `SESSION_ID` | The ULID of the session to delete |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--yes` | `-y` | Skip confirmation prompt |

---

## `agents session export`

Export a session as JSON to a file or stdout.

```bash
agents session export <SESSION_ID> [--output <FILE>] [--force]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `SESSION_ID` | The ULID of the session to export |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--output` | `-o` | Output file path (default: stdout) |
| `--force` | | Overwrite existing output file |

### Notes

- Parent directories are created automatically when writing to a file.
- Without `--force`, the command refuses to overwrite an existing file.
- The exported JSON includes a SHA-256 checksum for integrity validation.

---

## `agents session import`

Import a session from a JSON file previously exported with `session export`.

```bash
agents session import --input <FILE>
```

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--input` | `-i` | Input JSON file path (required) |

### Notes

- Validates schema version and SHA-256 checksum.
- Imported sessions receive fresh ULIDs to avoid ID collisions.

---

## `agents session tell`

Send a message to a session and receive an assistant response.

```bash
agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `PROMPT` | The message text to send |

### Options

| Flag | Description |
|------|-------------|
| `--session` | Target session ULID (required) |
| `--actor` | Override actor for this message |
| `--stream` | Stream the response in real-time |

### Notes

- In M3, actor execution is stubbed — the assistant echoes an acknowledgement.
- Both user and assistant messages are persisted with sequence ordering.
- The session's `updated_at` timestamp is refreshed after each message.

---

## Error Handling

| Error | Cause |
|-------|-------|
| `SessionNotFoundError` | The specified session ID does not exist |
| `SessionExportError` | Export operation failed |
| `SessionImportError` | Import failed due to bad schema or corrupt data |