xeroctl conversations

Overview

The conversations command group provides full lifecycle management for conversations and the items (messages) within them. Conversations are project-scoped resources mounted at /:project_id/v1/conversations. The CLI requires an --endpoint slug to choose the connection profile (base URL and auth); conversation IDs (prefixed conv_) are unique within the owning project, not partitioned per endpoint.

Conversations are used by the Responses API and chat interfaces to persist multi-turn context. Items within a conversation represent individual messages, function calls, or function call outputs in sequence order (item types: message, function_call, function_call_output).

Pattern

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

Global flags

The following flags are declared on the top-level xeroctl command and are accepted by every conversations subcommand. They are not advertised in each subcommand's --help output, but they are honored at runtime.

Flag	Description
`--dry-run`	Show what the command would do without making changes. Honored by `delete` and `delete-item`; ignored by read-only subcommands.

list

REST: GET /v1/conversations
Dry-run: ignored
Mutates: no

List all conversations visible to the endpoint's project. Results are ordered by created_at descending (newest first). This is the default subcommand when none is specified.

bash

                    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). Missing timestamps and empty metadata render as - in table output.

get

REST: GET /v1/conversations/{id}
Dry-run: ignored
Mutates: no

Show details of a specific conversation including all metadata key-value pairs.

bash

                    # Replace conv_abc123 with the ID printed by `conversations create`.
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

REST: POST /v1/conversations
Dry-run: ignored
Mutates: yes (insert)

Create a new conversation. Metadata key-value pairs are optional. The server enforces a cap of 16 entries and a 16 KB total serialized size for the metadata map.

bash

                    # 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 (repeatable; max 16 entries, max 16 KB total)

Note: Copy the conversation ID from the output for subsequent add-item, list-items, update, or delete calls.

update

REST: POST /v1/conversations/{id}
Dry-run: ignored
Mutates: yes (replace metadata)

Update the metadata on an existing conversation. At least one --metadata pair is required.

Replace semantics: The supplied metadata map fully replaces the existing one; it is not merged. Any keys previously set that are not re-supplied will be dropped. To preserve a key, re-pass it. The same 16-entry / 16 KB total caps apply as for create.

bash

                    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

REST: DELETE /v1/conversations/{id}
Dry-run: honored
Mutates: yes (soft delete)

Delete a conversation. By default, a confirmation prompt is shown. Use --force to skip it. The global --dry-run flag (see Global flags) reports what would be deleted without making changes.

Soft delete: Conversation records are not removed from the database; a deleted_at timestamp is set and the record is hidden from listing endpoints. Contact a platform admin if you need restoration.

bash

                    # 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

list-items

REST: GET /v1/conversations/{id}/items
Dry-run: ignored
Mutates: no

List items (messages and function calls) within a conversation. Items are returned in ascending sequence_number order (oldest insertion first) and include type, role, content preview, and timestamps.

bash

                    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

REST: POST /v1/conversations/{id}/items
Dry-run: ignored
Mutates: yes (append)

Add a new item to a conversation. The --content option is required. Defaults to type message with role user. The conversation ID conv_abc123 in the examples is a placeholder; substitute the ID printed by conversations create.

CLI surface gap: The current xeroctl client always sends a role field in the request body, even when the server does not require one (for example on function_call_output items). The server tolerates the extra field and persists it. The CLI also cannot today create items of type function_call, nor can it send the call_id, name, or arguments fields required to link a function call to its output, those fields exist in the REST schema (see Conversations API) but are not exposed as flags. To create fully spec-conformant function-call items, use the REST API directly until these flags are added.

bash

                    # 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
# Note: a stray role=user is sent on the wire today (see CLI surface gap above).
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 for `message`-type items: `user`, `assistant`, `system` (default: `user`). The CLI does not currently expose the `tool` role accepted by the REST API; use the REST endpoint directly to insert tool-role messages. The CLI sends this field unconditionally, including for non-`message` item types.
`--type <type>`	Item type: `message` or `function_call_output` (default: `message`). The REST schema also defines `function_call`, but the CLI cannot create that type today.

delete-item

REST: DELETE /v1/conversations/{id}/items/{item_id}
Dry-run: honored
Mutates: yes (soft delete)

Delete a specific item from a conversation. Requires both the conversation ID and the item ID. Substitute the IDs printed by conversations create and conversations list-items for the conv_abc123 / item_xyz placeholders. The global --dry-run flag (see Global flags) reports what would be deleted without making changes.

Soft delete: Items are not removed from the database; a deleted_at timestamp is set and the item is hidden from list-items. Contact a platform admin if you need restoration.

bash

                    # 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
                

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

Pagination

The list and list-items subcommands support cursor-based pagination. When more results are available, the CLI prints a hint line of the form (More results available, use --after <id> to paginate) after the table. Pass that ID as --after to fetch the next page.

bash

                    # 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

In the snippet below, conv_abc123 stands in for the ID printed by the first create call, copy it from that output and substitute it into the subsequent commands.

bash

                    # Create a conversation with metadata (note the printed conv_... id)
xeroctl conversations create --endpoint my-endpoint --metadata session=abc123

# Add a user turn (replace conv_abc123 with the id from the previous step)
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

bash

                    # 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
                

Overview

Subcommands

Global flags

list

Options

get

Arguments

Options

create

Options

update

Arguments

Options

delete

Arguments

Options

list-items

Arguments

Options

add-item

Arguments

Options

delete-item

Arguments

Options

Pagination

Examples

Create and Populate a Conversation

Inspect and Clean Up

xeroctl CLI

Conversations API

Responses API