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

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

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

---

agents session list

List all sessions with message counts and timestamps.

agents session list [--format <FORMAT>]

Options

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

JSON Output Shape

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

---

agents session show

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

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.

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.

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.

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.

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