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

# nextmail chats

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

## Commands

### `nextmail chats list`

List the assistant chats

```bash
nextmail 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.

Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an access token reaches the chats of the person who connected it. 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
nextmail chats list
```

With optional flags

```bash
nextmail chats list --q invoices
```

Walk every page and stop after 100 items

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

One JSON object per line when piped

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

Also available in: API [`GET /chats`](https://nextmail.sh/docs/api/reference/chats#get-chats); TypeScript [`nextmail.chats.list()`](https://nextmail.sh/docs/sdk/reference/chats#list); Python [`chats.list()`](https://nextmail.sh/docs/python/reference/chats#list); Ruby [`chats.list`](https://nextmail.sh/docs/ruby/reference/chats#list); PHP [`chats->list`](https://nextmail.sh/docs/php/reference/chats#list); Go [`Chats.List`](https://nextmail.sh/docs/go/reference/chats#list); Java [`chats().list`](https://nextmail.sh/docs/java/reference/chats#list); C# [`Chats.ListAsync`](https://nextmail.sh/docs/csharp/reference/chats#list).

### `nextmail chats get`

Retrieve a chat

```bash
nextmail 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.

Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an access token reaches the chats of the person who connected it. 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
nextmail chats get 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65
```

Print the raw JSON

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

Also available in: API [`GET /chats/{id}`](https://nextmail.sh/docs/api/reference/chats#get-chats-id); TypeScript [`nextmail.chats.get()`](https://nextmail.sh/docs/sdk/reference/chats#get); Python [`chats.get()`](https://nextmail.sh/docs/python/reference/chats#get); Ruby [`chats.get`](https://nextmail.sh/docs/ruby/reference/chats#get); PHP [`chats->get`](https://nextmail.sh/docs/php/reference/chats#get); Go [`Chats.Get`](https://nextmail.sh/docs/go/reference/chats#get); Java [`chats().get`](https://nextmail.sh/docs/java/reference/chats#get); C# [`Chats.GetAsync`](https://nextmail.sh/docs/csharp/reference/chats#get).

### `nextmail chats rename`

Rename a chat

```bash
nextmail 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.

Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an access token reaches the chats of the person who connected it. 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
nextmail chats rename 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65 'Quarterly invoices'
```

Print the raw JSON

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

Also available in: API [`PATCH /chats/{id}`](https://nextmail.sh/docs/api/reference/chats#patch-chats-id); TypeScript [`nextmail.chats.rename()`](https://nextmail.sh/docs/sdk/reference/chats#rename); Python [`chats.rename()`](https://nextmail.sh/docs/python/reference/chats#rename); Ruby [`chats.rename`](https://nextmail.sh/docs/ruby/reference/chats#rename); PHP [`chats->rename`](https://nextmail.sh/docs/php/reference/chats#rename); Go [`Chats.Rename`](https://nextmail.sh/docs/go/reference/chats#rename); Java [`chats().rename`](https://nextmail.sh/docs/java/reference/chats#rename); C# [`Chats.RenameAsync`](https://nextmail.sh/docs/csharp/reference/chats#rename).

### `nextmail chats delete`

Delete a chat

```bash
nextmail 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.

Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an access token reaches the chats of the person who connected it. 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
nextmail chats delete 8f3c2a71-5e9d-4b06-a1c4-7d2e9f0b3a65
```

Skip the confirmation, for scripts

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

Also available in: API [`DELETE /chats/{id}`](https://nextmail.sh/docs/api/reference/chats#delete-chats-id); TypeScript [`nextmail.chats.delete()`](https://nextmail.sh/docs/sdk/reference/chats#delete); Python [`chats.delete()`](https://nextmail.sh/docs/python/reference/chats#delete); Ruby [`chats.delete`](https://nextmail.sh/docs/ruby/reference/chats#delete); PHP [`chats->delete`](https://nextmail.sh/docs/php/reference/chats#delete); Go [`Chats.Delete`](https://nextmail.sh/docs/go/reference/chats#delete); Java [`chats().delete`](https://nextmail.sh/docs/java/reference/chats#delete); C# [`Chats.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/chats#delete).