205 lines
4.5 KiB
Markdown
205 lines
4.5 KiB
Markdown
# 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 |
|