# kindgi conversations

> Conversations: multi-turn threads with one agent version (list / get / open / close / messages)

## `kindgi conversations`

**Synopsis**

```sh signature
kindgi conversations <command>
```

Conversations: multi-turn threads with one agent version (list / get / open / close / messages).

**Commands**

| Command                                                                                                                            | Description                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`kindgi conversations list`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-list)             | List conversations, newest first.                                                                   |
| [`kindgi conversations get`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-get)               | Fetch a conversation by id.                                                                         |
| [`kindgi conversations open`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-open)             | Open a conversation with an agent version, pinned for every turn.                                   |
| [`kindgi conversations close`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-close)           | Close a conversation: it takes no more turns.                                                       |
| [`kindgi conversations unregister`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-unregister) | Unregister a conversation: reads, lists and recall no longer return it, and it takes no more turns. |
| [`kindgi conversations messages`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations-messages)     | List a conversation's messages, oldest first.                                                       |

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)

### `kindgi conversations list`

**Synopsis**

```sh signature
kindgi conversations list [--status=open|closed] [--opened-by=me] [--replays=exclude|include|only] [--limit=<n>] [--cursor=<c>]
```

List conversations, newest first.

**Options**

| Option                | Default                    | Description                                                                                                                               |
| --------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--cursor <value>`    | none                       | Resume after this cursor, from the previous page's `nextCursor`.                                                                          |
| `--limit <value>`     | `25` (at most `100`)       | The most conversations to return.                                                                                                         |
| `--opened-by <value>` | none (whoever opened them) | `me`: only the conversations you opened.                                                                                                  |
| `--replays <value>`   | `exclude`                  | Replay conversations (a comparison's replays): `exclude` (the default) leaves them out, `include` lists them too, `only` lists just them. |
| `--status <value>`    | none                       | Only the conversations with this status: `open` or `closed`.                                                                              |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

List the open conversations.

```sh
kindgi conversations list --status=open
```

List only comparison replays, a page at a time.

```sh
kindgi conversations list --replays=only --limit=10
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)

### `kindgi conversations get`

**Synopsis**

```sh signature
kindgi conversations get <conversation-id>
```

Fetch a conversation by id.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

From [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md):

```sh
pnpm exec kindgi conversations get <conversation-id>
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)

### `kindgi conversations open`

**Synopsis**

```sh signature
kindgi conversations open <agent-id> <version> [--title=<t>] [--project=<project-id>] [--participant=<id>]
```

Open a conversation with an agent version, pinned for every turn. A turn names it in its input: `kindgi runs start --agent=<agent-id> --input='{"userMessage": "…", "conversationId": "<conversation-id>"}'`.

**Options**

| Option                  | Default                      | Description                                                                                    |
| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `--participant <value>` | none                         | Your app's opaque id for the user the conversation is with.                                    |
| `--project <value>`     | the tenant's Default project | The project the conversation is in (`kindgi projects list`). Default: the agent's own project. |
| `--title <value>`       | `Untitled conversation`      | A title for the conversation. Default: "Untitled conversation".                                |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

From [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md):

```sh
pnpm exec kindgi conversations open acme.order-desk 0.1.0 --title="Order A-1002" --participant=customer-4411
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)

### `kindgi conversations close`

**Synopsis**

```sh signature
kindgi conversations close <conversation-id>
```

Close a conversation: it takes no more turns. Closing a closed one changes nothing.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

From [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md):

```sh
pnpm exec kindgi conversations close <conversation-id>
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)

### `kindgi conversations unregister`

**Synopsis**

```sh signature
kindgi conversations unregister <conversation-id>
```

Unregister a conversation: reads, lists and recall no longer return it, and it takes no more turns. The retention sweep removes it later.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

From [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md):

```sh
pnpm exec kindgi conversations unregister <conversation-id>
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)

### `kindgi conversations messages`

**Synopsis**

```sh signature
kindgi conversations messages <conversation-id> [--limit=<n>] [--cursor=<c>]
```

List a conversation's messages, oldest first.

**Options**

| Option             | Default              | Description                                                      |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| `--cursor <value>` | none                 | Resume after this cursor, from the previous page's `nextCursor`. |
| `--limit <value>`  | `25` (at most `100`) | The most messages to return.                                     |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.9/reference/cli.md#global-flags).

**Examples**

From [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md):

```sh
pnpm exec kindgi conversations messages <conversation-id>   # oldest first
```

**See also**

- [Hold a conversation](https://docs.kindgi.com/v0.1.9/guides/agents/conversations.md)
- [`kindgi conversations`](https://docs.kindgi.com/v0.1.9/reference/cli/conversations.md#kindgi-conversations)