xeroctl conversations
Manage conversations and conversation items. An endpoint slug (--endpoint) is always required. Part of the xeroctl CLI.
Overview
The conversations command group provides full lifecycle management for
conversations and the items (messages) within them. Conversations are scoped to an
endpoint and identified by a conversation ID prefixed with conv_.
Conversations are used by the Responses API and chat interfaces to persist multi-turn context. Items within a conversation represent individual messages or function call outputs in sequence order.
xeroctl conversations <subcommand> [id] --endpoint <slug> [options]
Subcommands
| Subcommand | Description |
|---|---|
list |
List all conversations for the endpoint (default) |
get <id> |
Show details of a specific conversation |
create |
Create a new conversation |
update <id> |
Update metadata on an existing conversation |
delete <id> |
Delete a conversation |
list-items <id> |
List items (messages) in a conversation |
add-item <id> |
Add a new item to a conversation |
delete-item <id> |
Delete a specific item from a conversation |
list
List all conversations for the endpoint. This is the default subcommand when none is specified.
xeroctl conversations list --endpoint my-endpoint
xeroctl conversations list --endpoint my-endpoint --limit 50
xeroctl conversations list --endpoint my-endpoint --after conv_abc123
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--limit <n> |
Maximum number of results (default 20) |
--after <id> |
Pagination cursor: conversation ID to start after |
Output columns: ID, Object, Created, Updated, Metadata (key count).
get
Show details of a specific conversation including all metadata key-value pairs.
xeroctl conversations get conv_abc123 --endpoint my-endpoint
xeroctl conversations get conv_abc123 --endpoint my-endpoint -o json
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
-o json |
Output full conversation object as JSON |
create
Create a new conversation. Metadata key-value pairs are optional and support up to 16 entries.
# Create a bare conversation
xeroctl conversations create --endpoint my-endpoint
# Create with metadata
xeroctl conversations create --endpoint my-endpoint --metadata env=prod user=alice
# Create with multiple metadata pairs
xeroctl conversations create --endpoint my-endpoint \
--metadata env=prod \
--metadata session=abc123
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--metadata <key=value> |
Metadata key=value pairs (up to 16, repeatable) |
Note: The full API key is shown once on creation -- copy the conversation ID from the output for subsequent operations.
update
Update the metadata on an existing conversation. At least one --metadata pair is required.
xeroctl conversations update conv_abc123 --endpoint my-endpoint --metadata env=staging
xeroctl conversations update conv_abc123 --endpoint my-endpoint \
--metadata env=staging \
--metadata user=bob
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--metadata <key=value> |
Metadata key=value pairs to set (at least one required) |
delete
Delete a conversation. By default, a confirmation prompt is shown. Use --force to skip it.
# With confirmation prompt
xeroctl conversations delete conv_abc123 --endpoint my-endpoint
# Skip confirmation
xeroctl conversations delete conv_abc123 --endpoint my-endpoint --force
# Dry run (no changes made)
xeroctl conversations delete conv_abc123 --endpoint my-endpoint --dry-run
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--force |
Skip the confirmation prompt |
--dry-run |
Show what would be deleted without making changes |
list-items
List items (messages) within a conversation. Items are returned in sequence order and include type, role, content preview, and timestamps.
xeroctl conversations list-items conv_abc123 --endpoint my-endpoint
xeroctl conversations list-items conv_abc123 --endpoint my-endpoint --limit 50 -o json
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--limit <n> |
Maximum number of results (default 20) |
--after <id> |
Pagination cursor: item ID to start after |
Output columns: ID, Type, Role, Seq (sequence number), Content (truncated to 50 chars), Created.
add-item
Add a new item to a conversation. The --content option is required. Defaults to type message with role user.
# Add a user message
xeroctl conversations add-item conv_abc123 --endpoint my-endpoint \
--role user \
--content "Hello, how are you?"
# Add an assistant message
xeroctl conversations add-item conv_abc123 --endpoint my-endpoint \
--role assistant \
--content "I am doing well, thank you."
# Add a function call output item
xeroctl conversations add-item conv_abc123 --endpoint my-endpoint \
--type function_call_output \
--content '{"result": "success"}'
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--content <text> |
Content of the item (required) |
--role <role> |
Message role: user, assistant, system (default: user) |
--type <type> |
Item type: message or function_call_output (default: message) |
delete-item
Delete a specific item from a conversation. Requires both the conversation ID and the item ID.
# With confirmation prompt
xeroctl conversations delete-item conv_abc123 --endpoint my-endpoint --item-id item_xyz
# Skip confirmation
xeroctl conversations delete-item conv_abc123 --endpoint my-endpoint --item-id item_xyz --force
# Dry run
xeroctl conversations delete-item conv_abc123 --endpoint my-endpoint --item-id item_xyz --dry-run
Arguments
| Argument | Description |
|---|---|
<id> |
The conversation ID (required) |
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
--item-id <id> |
The item ID to delete (required) |
--force |
Skip the confirmation prompt |
--dry-run |
Show what would be deleted without making changes |
Pagination
The list and list-items subcommands support cursor-based
pagination. When more results are available, the last ID in the current page is shown.
Pass it as --after to fetch the next page.
# First page
xeroctl conversations list --endpoint my-endpoint --limit 20
# Next page (use the last ID from the previous output)
xeroctl conversations list --endpoint my-endpoint --limit 20 --after conv_last123
Examples
Create and Populate a Conversation
# Create a conversation with metadata
xeroctl conversations create --endpoint my-endpoint --metadata session=abc123
# Add a user turn
xeroctl conversations add-item conv_abc123 --endpoint my-endpoint \
--role user --content "What is the capital of France?"
# Add an assistant turn
xeroctl conversations add-item conv_abc123 --endpoint my-endpoint \
--role assistant --content "The capital of France is Paris."
# List all items
xeroctl conversations list-items conv_abc123 --endpoint my-endpoint
Inspect and Clean Up
# List recent conversations in JSON format
xeroctl conversations list --endpoint my-endpoint -o json
# Get full details of one conversation
xeroctl conversations get conv_abc123 --endpoint my-endpoint
# Delete a specific item
xeroctl conversations delete-item conv_abc123 --endpoint my-endpoint \
--item-id item_xyz --force
# Delete the entire conversation
xeroctl conversations delete conv_abc123 --endpoint my-endpoint --force
