---
title: "openemail chats"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://openemail.uk/docs/cli/reference/chats"
area: "CLI"
category: "Reference"
---

# openemail chats

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `openemail chats list`

List the assistant chats

```bash
openemail chats list [flags]
```

Resolves one page of the conversations held with the assistant in the app, newest first, as its Chats page lists them, each with its title, how many messages it holds and when it last changed.

Only the workspace owner reaches the chats: an API key, or an access token the owner connected with every address. A token acting for a member is 403 `owner_only`, and a key or token limited to particular addresses or domains is 422 `capability_unsupported`.

Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.

- Scopes: `threads:read`.
- Needs a sign-in.
- Aliases: `ls`.

**Flags**

- `--q <value>`: Searches the titles.
- `--sort <value>` (default `"newest"`): `newest` (the default) or `oldest` by the last change, or `title`. A cursor carries on in the order it was handed out in.
- `--limit <n>` (default `25`): Page size, from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` of the previous page. Leave it out for the first page.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

```bash
openemail chats list
```

With optional flags

```bash
openemail chats list --q invoices
```

Walk every page and stop after 100 items

```bash
openemail chats list --all --max 100
```

One JSON object per line when piped

```bash
openemail chats list --all > chats.ndjson
```

Also available in: API [`GET /chats`](https://openemail.uk/docs/api/reference/chats#get-chats); SDK [`chats.list()`](https://openemail.uk/docs/sdk/reference/chats#list).

### `openemail chats get`

Retrieve a chat

```bash
openemail chats get <id> [flags]
```

Resolves one chat with the assistant by its id: its title, how many messages it holds and when it last changed.

Only the workspace owner reaches the chats: an API key, or an access token the owner connected with every address. A token acting for a member is 403 `owner_only`, and a key or token limited to particular addresses or domains is 422 `capability_unsupported`.

- Scopes: `threads:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Arguments**

- `<id>` (required): The chat id from `list`.

**Examples**

```bash
openemail chats get 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65
```

Print the raw JSON

```bash
openemail chats get 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65 --json
```

Also available in: API [`GET /chats/{id}`](https://openemail.uk/docs/api/reference/chats#get-chats-id); SDK [`chats.get()`](https://openemail.uk/docs/sdk/reference/chats#get).

### `openemail chats rename`

Rename a chat

```bash
openemail chats rename <id> <title> [flags]
```

Gives a chat with the assistant a new title, up to 120 characters, and resolves with the chat as it is now.

Only the workspace owner reaches the chats: an API key, or an access token the owner connected with every address. A token acting for a member is 403 `owner_only`, and a key or token limited to particular addresses or domains is 422 `capability_unsupported`.

- Scopes: `threads:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): The chat id from `list`.
- `<title>` (required): The new title, from 1 to 120 characters.

**Examples**

```bash
openemail chats rename 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65 'Quarterly invoices'
```

Print the raw JSON

```bash
openemail chats rename 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65 'Quarterly invoices' --json
```

Also available in: API [`PATCH /chats/{id}`](https://openemail.uk/docs/api/reference/chats#patch-chats-id); SDK [`chats.rename()`](https://openemail.uk/docs/sdk/reference/chats#rename).

### `openemail chats delete`

Delete a chat

```bash
openemail chats delete <id> [flags]
```

Deletes a chat with the assistant and every message in it, for good. Nothing the assistant did in the mailbox is undone.

Only the workspace owner reaches the chats: an API key, or an access token the owner connected with every address. A token acting for a member is 403 `owner_only`, and a key or token limited to particular addresses or domains is 422 `capability_unsupported`.

- Scopes: `threads:write`.
- Needs a sign-in.
- Asks you to confirm.
- Aliases: `rm`, `del`, `remove`.

**Arguments**

- `<id>` (required): The chat id from `list`.

**Examples**

```bash
openemail chats delete 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65
```

Skip the confirmation, for scripts

```bash
openemail chats delete 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65 --yes
```

Also available in: API [`DELETE /chats/{id}`](https://openemail.uk/docs/api/reference/chats#delete-chats-id); SDK [`chats.delete()`](https://openemail.uk/docs/sdk/reference/chats#delete).