erectl conversations

Overview

The conversations command group provides full lifecycle management for conversations and the items (messages) within them. Conversations are mounted at /:project_id/v1/conversations; the surface takes no endpoint slug. Use --context <name> to choose the connection profile (base URL and auth). Conversation IDs (prefixed conv_) are unique within the owning project, not partitioned per endpoint.

Each conversation belongs to one workspace of the project, and every command reaches only the conversations of the workspace its request resolves to. erectl names no workspace, so that is the only workspace of an API key confined to one, and the project's default workspace otherwise; a key confined to several workspaces is refused with 403 workspace_not_allowed. Conversations created before conversations recorded their workspace stay reachable by keys that are not confined to workspaces. See Workspace Scope.

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

erectl conversations <subcommand> [id] [options]

Subcommands

Subcommand	Description
`list`	List the conversations of the workspace the request resolves to (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 erectl 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 the conversations of the workspace the request resolves to. Results are ordered by created_at descending (newest first). This is the default subcommand when none is specified.

bash

                    erectl conversations list
erectl conversations list --limit 50
erectl conversations list --after conv_abc123
                

Options

Option	Description
`--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`.
erectl conversations get conv_abc123
erectl conversations get conv_abc123 -o json
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`-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
erectl conversations create

# Create with metadata
erectl conversations create --metadata env=prod user=alice

# Create with multiple metadata pairs
erectl conversations create \
  --metadata env=prod \
  --metadata session=abc123
                

Options

Option	Description
`--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

                    erectl conversations update conv_abc123 --metadata env=staging
erectl conversations update conv_abc123 \
  --metadata env=staging \
  --metadata user=bob
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`--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
erectl conversations delete conv_abc123

# Skip confirmation
erectl conversations delete conv_abc123 --force

# Dry run (no changes made)
erectl conversations delete conv_abc123 --dry-run
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`--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

                    erectl conversations list-items conv_abc123
erectl conversations list-items conv_abc123 --limit 50 -o json
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`--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 erectl 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
erectl conversations add-item conv_abc123 \
  --role user \
  --content "Hello, how are you?"

# Add an assistant message
erectl conversations add-item conv_abc123 \
  --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).
erectl conversations add-item conv_abc123 \
  --type function_call_output \
  --content '{"result": "success"}'
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`--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
erectl conversations delete-item conv_abc123 --item-id item_xyz

# Skip confirmation
erectl conversations delete-item conv_abc123 --item-id item_xyz --force
                

Arguments

Argument	Description
`<id>`	The conversation ID (required)

Options

Option	Description
`--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
erectl conversations list --limit 20

# Next page (use the last ID from the previous output)
erectl conversations list --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)
erectl conversations create --metadata session=abc123

# Add a user turn (replace conv_abc123 with the id from the previous step)
erectl conversations add-item conv_abc123 \
  --role user --content "What is the capital of France?"

# Add an assistant turn
erectl conversations add-item conv_abc123 \
  --role assistant --content "The capital of France is Paris."

# List all items
erectl conversations list-items conv_abc123
                

Inspect and Clean Up

bash

                    # List recent conversations in JSON format
erectl conversations list -o json

# Get full details of one conversation
erectl conversations get conv_abc123

# Delete a specific item
erectl conversations delete-item conv_abc123 \
  --item-id item_xyz --force

# Delete the entire conversation
erectl conversations delete conv_abc123 --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

erectl CLI

Conversations API

Responses API