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.

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

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)

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

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

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.

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.

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

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

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

• 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