---
title: "Commands"
description: "How a command reads, the global flags, every hand-written command and every resource namespace."
url: "https://nextmail.sh/docs/cli/commands"
area: "CLI"
category: "Using it"
---

# Commands

How a command reads, the global flags, every hand-written command and every resource namespace.

## How a command reads

**Grammar**

```
nextmail <command> [subcommand] [arguments] [flags]
```

- Flags go anywhere after the command, before or after the arguments. Global flags such as `--profile` and `--json` may also come before it, and any other flag placed there stops with a hint to move it after the command name.
- A value follows its flag after a space or an equals sign, so `--limit 50` and `--limit=50` are the same. Short flags take values too, as in `-n 50`.
- A value that starts with a dash needs the equals sign, as in `--subject=-draft-`, because after a space it reads as the next flag and the first one is reported as missing its value. Negative numbers work either way. An empty value is a usage error rather than a quiet default.
- A switch is on with `--flag` and off with `--no-flag`, and `--flag=true` and `--flag=false` work too.
- A list is comma separated or repeated: `--to ada@example.com,bob@example.com`, or `--to` twice.
- Everything after `--` is an argument and never a flag, which is how a search for `-from:ada` gets through.
- An unknown command or flag stops with exit code `2` and suggests the closest match.

## Global flags

| Flag | What it does |
| --- | --- |
| -h, --help | Help for the command or group. With `--json`, the same help as one JSON document |
| -v, --version | Print the CLI version |
| --json | Only JSON on stdout, errors as JSON on stderr, and never a prompt |
| -y, --yes | Confirm destructive actions without asking. Never skips a verification code |
| --dry-run | Run the reads, then print the first request that would change something instead of sending it, and exit with code `0`. Skips confirmations, since nothing is sent |
| --profile <name> | Use this saved profile, like `NEXTMAIL_PROFILE`, even when `NEXTMAIL_API_KEY` is set |
| --api-key <key> | Use this API key for this command only, ignoring profiles |
| --base-url <url> | The API origin for an API key or a command that sends no credential, like `NEXTMAIL_BASE_URL`. A saved sign-in refuses any other origin with exit code `2`, so sign in to it as its own profile |
| --no-input | Never prompt. A missing value stops with exit code `2` |
| --no-color | No colour, like `NO_COLOR` and `FORCE_COLOR=0` |
| --debug | Print request ids, the failed request and stack traces |

## Hand-written commands

These are written for people: they ask for what is missing, format what they print, and combine several API calls where that helps.

| Command | What it does |
| --- | --- |
| login | Sign in with your browser, or save an API key |
| whoami | Who you are signed in as, with the workspace, scopes and expiry |
| status | What `whoami` shows, plus your sender addresses and the state of each domain |
| verify | Enter a verification code now, so sensitive commands run for 60 minutes |
| logout | Sign out and forget a profile |
| profile list, use, current, remove | List, switch and remove saved sign-ins |
| send | Send, schedule, or translate and send an email |
| inbox [folder] | List the threads in a folder |
| search <query> | Search mail with the syntax the app uses |
| read <thread-id> | Read a thread, message by message |
| reply <thread-id> | Reply to the last message on a thread |
| archive, unarchive, trash, star, unstar | File one or more threads |
| mark read, mark unread | Mark threads read or unread |
| snooze, unsnooze | Hide threads until later, or bring them back now |
| label add, label remove | Put labels on threads, or take them off |
| temp new, list, read, watch, delete | Disposable inboxes, with no sign-in |
| ai translate, languages, compose, summarize | Translate, write and summarise mail with AI |
| mcp config, tools, call, serve | Connect AI clients, or call MCP tools yourself |
| docs ask, open, read | Ask, open and read this documentation |
| agents | A guide for AI agents and scripts that drive the CLI, in Markdown or as JSON |
| open [page] | Open a page of the web app |
| api <method> <path> | Call any REST endpoint with your sign-in |
| update | Check npm for a newer release |
| completion <shell> | Print a completion script for bash, zsh or fish |
| version | Print the CLI, SDK and runtime versions |
| help [command] | Show the help of any command |

## Resource commands

Every method of the SDK is also a command, `nextmail <namespace> <verb>`. The namespace is the SDK namespace in kebab case, and the verb is the method name in kebab case, so `keys.listRequests` is `nextmail keys list-requests`. Together they cover the whole REST API.

**Terminal**

```
nextmail domains list
nextmail domains create --domain acme.com
nextmail rules create --data @rule.json
nextmail keys list-requests 9f2c1a4b7e05d3862c1f0a44 --failed-only --all
nextmail files download file_6bb640f5b99e47deb758f1f5 --out report.pdf
```

- An id the method takes is an argument, as in `nextmail domains get <id>`. Each field of the request body is a flag named after it in kebab case: `replyTo` is `--reply-to`, and `color.backgroundColor` is `--color-background-color`.
- Three fields whose flag would clash with a global flag are renamed: `--template-version`, `--label-color` and `--provider-key`. The provider key, in `--provider-key` and in `provider-imports inspect`, also takes `-` for stdin or `@path` for a file, which keeps it out of your shell history.
- `--data` takes the whole body as JSON, inline, from a file with `@path`, or from stdin with `-`, and any flag you pass as well overrides its key. A flag that takes an object reads JSON the same way.
- Numbers and switches are read as such, and lists are comma separated or repeated.
- A missing required value is asked for in a terminal, and is a usage error (exit code `2`) anywhere else.
- A list verb reads one page. `--limit` sets its size and `--cursor` carries on from the cursor it printed. `--all` reads every page and streams the items, `--max <n>` stops after that many, and `--ndjson` prints one JSON object per line. With `--json` it prints one `{ items, hasMore, nextCursor }` document, `--all` included.
- Anything destructive, such as deleting, revoking, rotating, cancelling or emptying, asks you to confirm, unless you pass `--yes`.
- A download is written to the file in `--out`, and to stdout only when stdout is not a terminal.
- A table fits the terminal. When even the narrowest columns do not fit, the last ones are left out, and a note names them.

`nextmail <namespace> <verb> --help` shows each argument and flag with its type, the scopes the call needs, its method and path, what it returns, and the notes from the API reference.

## Every namespace

Also lists the other names a namespace answers to.

| Namespace | Also | Verbs |
| --- | --- | --- |
| me |  | `get`, `ping`, `rotate`, `list-requests`, `list-activity`, `stats` |
| keys | `key` | `list`, `get`, `create`, `update`, `delete`, `rotate`, `revoke`, `list-requests`, `list-activity`, `list-workspace-requests`, `list-workspace-activity`, `stats` |
| addresses | `address` | `list` |
| languages | `language` | `list` |
| emails | `email` | `send`, `send-batch`, `translate`, `check`, `list`, `get`, `list-events`, `get-tracking`, `cancel`, `reschedule`, `update`, `compose`, `rewrite`, `suggest-subject` |
| templates | `template` | `list`, `get`, `create`, `update`, `duplicate`, `replace-content`, `delete`, `list-versions`, `get-version`, `publish`, `restore-version`, `delete-version`, `list-starters`, `get-starter`, `list-fonts`, `render`, `preview`, `get-analytics`, `list-sends`, `send` |
| tracking |  | `list`, `get-stats`, `get`, `list-opens`, `list-clicks` |
| threads | `thread` | `list`, `get`, `update`, `trash`, `snooze`, `unsnooze`, `list-attachments`, `list-notes`, `create-note`, `update-note`, `delete-note`, `reorder-notes`, `counts`, `summary`, `restore`, `delete`, `unsubscribe`, `get-event`, `reply-suggestions`, `mute`, `unmute`, `list-sender-categories`, `set-sender-category`, `clear-sender-category` |
| drafts | `draft` | `list`, `get`, `create`, `update`, `delete` |
| labels |  | `list`, `list-colors`, `get`, `create`, `update`, `delete`, `test` |
| contacts | `contact` | `list`, `get`, `create`, `update`, `delete`, `set-audiences`, `list-people`, `save`, `delete-many`, `set-photo`, `remove-photo`, `block`, `unblock`, `list-threads`, `activity` |
| audiences | `audience` | `list`, `growth`, `get`, `create`, `update`, `delete`, `empty`, `list-contacts`, `add-contact`, `remove-contact`, `add-contacts`, `remove-contacts`, `import-contacts` |
| forms | `form` | `list`, `create`, `list-starters`, `get-starter`, `get`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `list-submissions`, `get-submission`, `delete-submission`, `delete-submissions`, `approve-submission`, `resend-confirmation`, `subscribe`, `design`, `redesign` |
| broadcasts | `broadcast` | `preview`, `send`, `list`, `get`, `stats`, `list-recipients`, `get-recipient`, `cancel` |
| domains | `domain` | `list`, `get`, `create`, `verify`, `update`, `delete`, `get-logo`, `set-logo`, `remove-logo`, `set-logo-certificate`, `remove-logo-certificate`, `list-addresses`, `create-address`, `get-address`, `update-address`, `delete-address`, `set-address-photo`, `remove-address-photo`, `list-address-forwards`, `add-address-forwards`, `update-address-forward`, `delete-address-forward`, `resend-address-forward-consent`, `list-address-members`, `get-address-login`, `set-address-login`, `delete-address-login`, `get-mail-app-settings`, `list-app-passwords`, `create-app-password`, `delete-app-password`, `send-mail-app-setup`, `get-dns`, `set-dns-zone`, `sync-dns` |
| rules | `rule` | `list`, `get`, `create`, `update`, `delete`, `reorder`, `test`, `list-runs` |
| webhooks | `webhook` | `list`, `get`, `create`, `update`, `delete`, `rotate-secret`, `test`, `list-deliveries`, `get-delivery`, `replay-delivery`, `list-workspace-deliveries`, `list-activity`, `list-workspace-activity`, `list-events`, `stats` |
| imports | `import` | `list`, `get`, `create`, `upload-state`, `upload-chunk`, `start`, `cancel`, `list-failures`, `delete-upload`, `import-files` |
| provider-imports | `provider-import`, `providerImports` | `inspect`, `create`, `list`, `get`, `cancel` |
| calendar |  | `list-events`, `get-event`, `get-event-ics`, `create-event`, `update-event`, `delete-event`, `cancel-event`, `respond-to-event` |
| settings | `setting` | `get`, `update` |
| roles | `role` | `list`, `get`, `create`, `update`, `delete`, `list-permissions` |
| members | `member` | `list`, `get`, `add`, `update`, `remove`, `grant-address`, `revoke-address`, `list-invitations`, `revoke-invitation`, `resend-invitation`, `grant-domain`, `revoke-domain` |
| suppressions | `suppression` | `list`, `get`, `add`, `remove` |
| files | `file` | `list`, `get`, `stats`, `download`, `list-links`, `create-link`, `revoke-link`, `revoke-all-links`, `upload`, `delete`, `delete-many` |
| temp-mail | `tempMail` | `list-domains`, `create`, `get`, `extend`, `delete`, `list-messages`, `get-message`, `delete-message`, `list-attachments` |
| tools |  | `check-dmarc`, `check-bimi`, `check-deliverability`, `check-address`, `check-addresses` |
| support |  | `send` |
| encryption |  | `list-keys`, `publish-key`, `lookup-keys` |
| chats |  | `list`, `get`, `rename`, `delete` |
| exports |  | `preview`, `list`, `get`, `start`, `download` |
| senders |  | `get`, `research` |
| analytics |  | `mailbox`, `sending` |
| subscriptions |  | `list`, `list-domains`, `keep`, `unsubscribe`, `unsubscribe-many`, `unsubscribe-domain`, `move`, `move-many` |
| dns-connections | `dnsConnections` | `list`, `get`, `delete` |
| billing |  | `get`, `list-plans`, `get-usage`, `list-alerts`, `list-countries`, `get-pay-as-you-go`, `set-pay-as-you-go`, `set-pay-as-you-go-limit`, `confirm-pay-as-you-go`, `start-checkout`, `open-portal`, `list-invoices`, `get-invoice`, `save-invoice-details`, `list-add-ons`, `start-add-on-checkout`, `cancel-add-on` |
| knowledge |  | `list`, `levels`, `usage`, `search`, `create-note`, `add-link`, `upload-file`, `get`, `update`, `delete`, `refresh`, `stats`, `list-suggestions`, `accept-suggestion`, `dismiss-suggestion`, `list-flags`, `dismiss-flag`, `list-connectors`, `add-connector`, `get-connector`, `update-connector`, `delete-connector`, `sync-connector`, `draft-from-thread` |
| follow-ups | `followUps` | `list`, `set`, `cancel` |
| out-of-office | `outOfOffice` | `list`, `set`, `clear` |
| sending |  | `list-streams`, `resume-stream`, `list-dedicated-ips`, `get-dedicated-ip` |
| signatures |  | `list`, `get`, `create`, `update`, `delete`, `copy` |
| tasks | `task` | `list`, `get`, `create`, `update`, `delete`, `pause`, `resume`, `run`, `list-runs`, `get-run`, `start-run`, `cancel-run`, `list-approvals`, `get-approval`, `approve`, `deny` |
| connectors | `connector` | `list-apps`, `get-app`, `list-categories`, `list`, `get`, `connect`, `update`, `disconnect`, `reconnect`, `list-actions`, `get-action`, `run-action`, `list-calls` |

Each area has a page of its own, with every command in its namespaces, the scopes they need and worked examples. Every command is also on one page of its own, with the endpoint and scope of each.

- [Sending and tracking email](https://nextmail.sh/docs/cli/emails.md): The emails and tracking namespaces: send, batch, translate, schedule and cancel, then delivery, opens and clicks.
- [Threads, drafts and labels](https://nextmail.sh/docs/cli/mailbox.md): The threads, drafts and labels namespaces, and how the mail commands use them.
- [Contacts, audiences and broadcasts](https://nextmail.sh/docs/cli/contacts.md): The address book, audiences, broadcasts and the suppression list.
- [Domains and addresses](https://nextmail.sh/docs/cli/domains.md): Domains, their DNS records and addresses, and the addresses you can send as.
- [Templates, rules and webhooks](https://nextmail.sh/docs/cli/automation.md): Stored templates, rules that file arriving mail, and signed events for your own server.
- [Files, imports and settings](https://nextmail.sh/docs/cli/files.md): Files, mailbox imports, imports from other providers, the calendar found in mail, and settings.
- [Keys, members and roles](https://nextmail.sh/docs/cli/workspace.md): API keys, members, roles, your own credential, languages, disposable inboxes and any REST call.
- [Sign-up forms](https://nextmail.sh/docs/cli/forms.md): Forms, the people who fill them in, and signing someone up.
- [Automations and events](https://nextmail.sh/docs/cli/automations.md): Automations, the people inside them and the events that move them.
- [Every command](https://nextmail.sh/docs/cli/reference/commands.md): All of them on one page, with the endpoint and scope of each.
- [Tasks](https://nextmail.sh/docs/cli/tasks.md): Tasks, the runs they make and the approvals those runs ask for.
- [Booking pages](https://nextmail.sh/docs/cli/bookings.md): Booking pages, the times they offer and the meetings guests booked.
- [Connectors](https://nextmail.sh/docs/cli/connectors.md): Connectors, the apps that can be connected, their actions and the record of what was done.

## Aliases

| Alias | For |
| --- | --- |
| ls | `list` |
| show, view | `get` |
| new, add | `create` |
| edit | `update` |
| rm, del, remove | `delete` |
| nextmail ls | `nextmail inbox` |
| nextmail show | `nextmail read` |

In `members` and `suppressions`, whose verbs are `add` and `remove`, `new` and `create` lead to `add`, and `rm`, `del` and `delete` lead to `remove`. A few hand-written subcommands have aliases of their own, which their help lists.

## Any REST call

`nextmail api <method> <path>` sends one request to the REST API through the same transport as every other command, so your profile or key, token renewal and verification codes all apply. A path on its own is a `GET`. A JSON answer prints formatted, and a failed request prints the API error and exits with the matching code.

**Terminal**

```
nextmail api /keys/self
nextmail api GET /threads --query folder=inbox --query limit=5
nextmail api POST /labels --data '{"name":"Receipts"}'
nextmail api PATCH /threads/CAHk7pQ2x9LmZ4 --data @patch.json
nextmail api GET /files/file_6bb640f5b99e47deb758f1f5/content --out report.pdf
```

- `-d`, `--data` takes the body as inline JSON, from a file with `@path`, or from stdin with `-`. `-q`, `--query` and `-H`, `--header` take `key=value` and can be repeated, and `-o`, `--out` saves the answer to a file as it came.
- The path is relative to the API origin. A full URL, a path that would leave the origin and an `Authorization` header are refused with exit code `2` before anything is sent, because the CLI sets the credential itself.
- A `DELETE`, and any call a resource command would confirm, such as revoking or rotating a key, cancelling a send or sending a broadcast, asks you to confirm first. Unattended it stops with exit code `2` unless you pass `--yes`.

## Help

**Terminal**

```
nextmail --help
nextmail help send
nextmail domains --help
nextmail domains create --help
nextmail domains create --help --json
```

`nextmail --help` lists every command by what it is for. A group lists its subcommands with examples, and a command shows everything it takes. `nextmail docs open cli` opens these pages.

Add `--json` to any of them and the same help prints as one JSON document, with every argument, flag, scope and example, for a script or an AI agent to read. The For AI agents page describes its fields.