cleveragents-core/docs/reference/session_cli.md

# 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 or Markdown |
| `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`) |

### Rich Output Panels

The `rich` format renders three panels:

- **Session** — session ID, actor, namespace, and creation timestamp.
- **Settings** — automation profile, streaming, context, memory, and max history.
- **Actor Details** — provider, model, temperature, and context window (only shown when an actor is bound).

Followed by a `✓ OK Session created` success message.

### 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`) |

### Rich Output

The `rich` format renders a sessions table with columns: **ID**, **Name**, **Actor**,
**Messages**, and **Updated**. After the table, a **Summary** panel is shown with:

| Field | Description |
|-------|-------------|
| Total | Number of sessions |
| Most Recent | Name or full ULID of the most recently updated session |
| Oldest | Name or full ULID of the oldest session |
| Total Messages | Sum of messages across all sessions |
| Storage | Estimated storage used |

Followed by a `✓ OK N sessions listed` success message.

### JSON Output Shape

```json
{
  "sessions": [
    {
      "id": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
      "name": "my-session",
      "actor": "openai/gpt-4",
      "messages": 5,
      "updated": "2026-04-02T21:56:04"
    }
  ],
  "summary": {
    "total": 1,
    "most_recent": "my-session",
    "oldest": "my-session",
    "total_messages": 5,
    "storage": "0 KB"
  }
}
```

---

## `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`) |

### Rich Output Panels

- **Session Summary** — session ID, actor, namespace, message count, created/updated timestamps, and **Automation** profile.
- **Recent Messages** — table of the last 5 messages (role, content preview, timestamp).
- **Linked Plans** — list of plan IDs linked to this session (if any).
- **Token Usage** — input tokens, output tokens, and estimated cost.
- **Cost Budget** — total cost, max cost, utilization percentage, and remaining budget (if a budget is configured).

Followed by a `✓ OK Session details loaded` success message.

---

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

### Rich Output Panels

After deletion, the `rich` format renders:

- **Deletion Summary** — session ID, messages removed, storage freed, and plans orphaned.
- **Cleanup** — backup status, log preservation, context cleared, and checkpoint status.

Followed by a `✓ OK Session deleted` success message.

---

## `agents session export`

Export a session as JSON or Markdown to a file or stdout.

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

### 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 |
| `--format` | | Export format: `json` (default, re-importable) or `md` (Markdown transcript, lossy) |

### Rich Output Panels

On success, the `rich` format renders three panels:

- **Session Export** — session ID, output path (or `(stdout)` for stdout), message count,
  file size, and format.
- **Contents** — messages count, plan references, metadata keys, actor config inclusion,
  and schema version.
- **Integrity** — SHA-256 checksum (`sha256:xxxx...xxxx`) and encrypted flag.

Followed by a `✓ OK Export completed` success message.

Example output:

```
╭─ Session Export ────────────────────╮
│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
│ Output: /tmp/weekly-planning.json   │
│ Messages: 6                         │
│ Size: 24 KB                         │
│ Format: JSON                        │
╰─────────────────────────────────────╯

╭─ Contents ─────────────────╮
│ Messages: 6                │
│ Plan References: 1         │
│ Metadata Keys: 2           │
│ Actor Config: included     │
│ Schema Version: v3         │
╰────────────────────────────╯

╭─ Integrity ──────────────────╮
│ Checksum: sha256:7a9b...42c1 │
│ Encrypted: no                │
╰──────────────────────────────╯

✓ OK Export completed
```

### 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 `sha256:`-prefixed checksum for integrity validation.
- The `md` format produces a human-readable Markdown transcript with session metadata,
  full message history (role/timestamp/content), and linked plan references. It cannot
  be re-imported.
- When exporting to stdout, the output path in the panel shows `(stdout)`.

### Examples

```bash
# Export as JSON (default)
agents session export 01HXYZ... -o session.json

# Export as Markdown transcript
agents session export 01HXYZ... --format md -o session.md

# Overwrite existing file
agents session export 01HXYZ... -o session.json --force

# Export to stdout
agents session export 01HXYZ...
```

---

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

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