chat

mutations carry an auto-generated Idempotency-Key so a network retry never double-creates, double-deletes, or double-renames. send streams the assistant reply to stdout as deltas arrive (ai-sdk v3 line-prefixed protocol).

verbs

new

start a new conversation.

owlette chat new --site <siteId> [--machine <machineId>] [--title <title>] [--idempotency-key <key>]

backing endpoint: POST /api/cortex/conversations. emits { conversationId, siteId, machineId, title } on success.

list

cursor-paged conversation list for a site.

owlette chat list --site <siteId> [--limit <n>] [--cursor <token>]

backing endpoint: GET /api/cortex/conversations?siteId=&page_size=&page_token=. tabular output renders conversationId | title | machine | messages | updatedAt; --json emits { conversations, nextPageToken }.

send

append a message and stream the assistant reply to stdout.

owlette chat send <conversationId> <message> [--idempotency-key <key>]

text deltas (ai-sdk frame 0:"…") are flushed to stdout as they arrive so users see the model think rather than wait for the full reply. error frames (3:"…") are surfaced on stderr and set exit 1. with --json the cli buffers the full reply and emits { conversationId, content } once at the end.

backing endpoint: POST /api/cortex/conversations/{conversationId} (AI-SDK text stream). idempotency-key is sent for replay safety even though the server skips its cache for streamed responses.

delete

soft-delete a conversation (recoverable for 30 days).

owlette chat delete <conversationId> [--yes] [--idempotency-key <key>]

interactive [y/N] prompt by default. --yes skips it. when stdin is not a tty and --yes was not supplied, the cli refuses rather than delete silently.

backing endpoint: DELETE /api/cortex/conversations/{conversationId}. responses include alreadyDeleted: true when the conversation was already tombstoned (still exit 0).

rename

set a new title on a conversation.

owlette chat rename <conversationId> <title> [--idempotency-key <key>]

backing endpoint: PATCH /api/cortex/conversations/{conversationId} with body { title }.

exit codes

• 0 — success
• 1 — generic error (network, 5xx, malformed stream, upstream cortex error, bad --limit, missing required flag, non-tty without --yes)
• 2 — usage error (no token)

notes

• scope: site-scoped on every verb; new accepts an optional --machine for single-machine cortex sessions.
• tier: ready (public-api Wave 2.9).
• streaming: only send streams. new/list/delete/rename are simple json round-trips.
• idempotency: every mutation auto-generates a unique key; pass --idempotency-key to deduplicate across script-level retries.
• soft-delete: delete is reversible for 30 days via the dashboard. there is no hard-delete verb on the cli.
• see also: cortex API docs at docs/api/cortex.md; per-machine context is fetched server-side from the machine's last heartbeat and process snapshot.