---
title: "Command reference"
description: "Every machinemail command, generated from the CLI's own command tree: usage, arguments, flags with types and defaults, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands"
---

# Command reference

> Every machinemail command, generated from the CLI's own command tree: usage, arguments, flags with types and defaults, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands

Every command the CLI has, generated from the same data as `machinemail --help`, grouped as `--help` groups them. `mm` is the same binary, so every example also works with `mm` in place of `machinemail`.

```bash
machinemail <command> [args] [flags]
machinemail <resource> <action> [args] [flags]
```

Resource commands are generated from the [API reference](https://machinemail.dev/docs/reference/api): path parameters are arguments, query parameters and body fields are flags. A route that also exists under a pod or an inbox is one command with a `--pod` or `--inbox` flag. Flag values are typed: integers are checked, booleans take `--flag`, `--flag=false` or `--no-flag`, arrays repeat the flag, objects take JSON, and `-d/--data` takes the whole body as JSON, `@file` or `-` for stdin. See [Output and scripting](https://machinemail.dev/docs/cli/output-and-scripting) for output formats and exit codes.

## Global flags

Every command accepts these. Command flags go after `<resource> <action>`.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--json` | `boolean` |  | Print raw JSON, even on a terminal. |
| `--fields <a,b.c>` | `string` |  | Only these fields (dot paths), in JSON and tables. |
| `--profile <name>` | `string` |  | Config profile (MACHINEMAIL_PROFILE). |
| `--api-key <key|->` | `string` |  | API key, or - to read it from stdin. Prefer MACHINEMAIL_API_KEY or a profile: a literal key shows in ps and shell history. |
| `--base-url <url>` | `string` |  | API origin (MACHINEMAIL_BASE_URL). |
| `-v, --verbose` | `boolean` |  | Log requests and responses to stderr (keys redacted). |
| `-q, --quiet` | `boolean` |  | No spinners or success lines; errors still print. |
| `-y, --yes` | `boolean` |  | Confirm deletes without asking (needed when there is no terminal to ask on). |
| `--color` | `boolean` |  | Color on or off (default: on for a terminal; NO_COLOR also turns it off). Default: `on for a terminal`. |
| `-h, --help` | `boolean` |  | Show help. |

## Getting started

| Command                                                                | Summary                                                                         |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`login`](https://machinemail.dev/docs/cli/commands/setup#login)       | Sign in with the browser (or an API key) and save the key to a profile          |
| [`whoami`](https://machinemail.dev/docs/cli/commands/setup#whoami)     | Show the key, profile and API in use, and check the key                         |
| [`doctor`](https://machinemail.dev/docs/cli/commands/setup#doctor)     | Check the config, connectivity, key, clock and CLI version                      |
| [`register`](https://machinemail.dev/docs/cli/commands/setup#register) | Register this agent (auth.md): a sandbox inbox and credentials, no human needed |
| [`claim`](https://machinemail.dev/docs/cli/commands/setup#claim)       | Get a new claim code for a registered agent, and wait for a human to claim it   |
| [`logout`](https://machinemail.dev/docs/cli/commands/setup#logout)     | Remove the stored key from a profile, and optionally revoke it                  |

## Mail

| Command                                                                                                     | Summary                                                                    |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`send`](https://machinemail.dev/docs/cli/commands/mail#send)                                               | Send an email from an inbox                                                |
| [`read`](https://machinemail.dev/docs/cli/commands/mail#read)                                               | Show a message: headers, trust verdict and agent-safe text                 |
| [`wait`](https://machinemail.dev/docs/cli/commands/mail#wait)                                               | Wait for a message to arrive (and extract a code or magic link with --otp) |
| [`tail`](https://machinemail.dev/docs/cli/commands/mail#tail)                                               | Follow live events (messages, deliveries, inboxes) as they happen          |
| [`messages attachment`](https://machinemail.dev/docs/cli/commands/messages#messages-attachment)             | Get attachment                                                             |
| [`messages batch-get`](https://machinemail.dev/docs/cli/commands/messages#messages-batch-get)               | Batch get messages                                                         |
| [`messages batch-update`](https://machinemail.dev/docs/cli/commands/messages#messages-batch-update)         | Batch update messages                                                      |
| [`messages delete`](https://machinemail.dev/docs/cli/commands/messages#messages-delete)                     | Delete message                                                             |
| [`messages download`](https://machinemail.dev/docs/cli/commands/messages#messages-download)                 | Download attachment                                                        |
| [`messages forward`](https://machinemail.dev/docs/cli/commands/messages#messages-forward)                   | Forward message                                                            |
| [`messages get`](https://machinemail.dev/docs/cli/commands/messages#messages-get)                           | Get message                                                                |
| [`messages list`](https://machinemail.dev/docs/cli/commands/messages#messages-list)                         | List messages                                                              |
| [`messages raw`](https://machinemail.dev/docs/cli/commands/messages#messages-raw)                           | Get raw message                                                            |
| [`messages reply`](https://machinemail.dev/docs/cli/commands/messages#messages-reply)                       | Reply to a message                                                         |
| [`messages reply-all`](https://machinemail.dev/docs/cli/commands/messages#messages-reply-all)               | Reply to all recipients of a message                                       |
| [`messages search`](https://machinemail.dev/docs/cli/commands/messages#messages-search)                     | Search messages                                                            |
| [`messages send`](https://machinemail.dev/docs/cli/commands/messages#messages-send)                         | Send message                                                               |
| [`messages trust`](https://machinemail.dev/docs/cli/commands/messages#messages-trust)                       | Get message trust report                                                   |
| [`messages update`](https://machinemail.dev/docs/cli/commands/messages#messages-update)                     | Update message                                                             |
| [`threads delete`](https://machinemail.dev/docs/cli/commands/threads#threads-delete)                        | Delete thread                                                              |
| [`threads get`](https://machinemail.dev/docs/cli/commands/threads#threads-get)                              | Get thread                                                                 |
| [`threads list`](https://machinemail.dev/docs/cli/commands/threads#threads-list)                            | List threads                                                               |
| [`threads search`](https://machinemail.dev/docs/cli/commands/threads#threads-search)                        | Search threads                                                             |
| [`threads update`](https://machinemail.dev/docs/cli/commands/threads#threads-update)                        | Update thread                                                              |
| [`drafts create`](https://machinemail.dev/docs/cli/commands/drafts#drafts-create)                           | Create draft                                                               |
| [`drafts delete`](https://machinemail.dev/docs/cli/commands/drafts#drafts-delete)                           | Delete draft                                                               |
| [`drafts download-attachment`](https://machinemail.dev/docs/cli/commands/drafts#drafts-download-attachment) | Download draft attachment                                                  |
| [`drafts get`](https://machinemail.dev/docs/cli/commands/drafts#drafts-get)                                 | Get draft                                                                  |
| [`drafts list`](https://machinemail.dev/docs/cli/commands/drafts#drafts-list)                               | List drafts                                                                |
| [`drafts send`](https://machinemail.dev/docs/cli/commands/drafts#drafts-send)                               | Send draft                                                                 |
| [`drafts update`](https://machinemail.dev/docs/cli/commands/drafts#drafts-update)                           | Update draft                                                               |
| [`inbound raw`](https://machinemail.dev/docs/cli/commands/inbound#inbound-raw)                              | Inject raw message                                                         |

## Inboxes

| Command                                                                                             | Summary                                               |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`inboxes availability`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-availability)    | Check inbox availability                              |
| [`inboxes create`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-create)                | Create inbox                                          |
| [`inboxes delete`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-delete)                | Delete inbox                                          |
| [`inboxes export`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-export)                | Export inbox                                          |
| [`inboxes get`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-get)                      | Get inbox                                             |
| [`inboxes list`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-list)                    | List inboxes                                          |
| [`inboxes new`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-new)                      | Create an inbox and print its address (pipe-friendly) |
| [`inboxes search`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-search)                | Search inboxes                                        |
| [`inboxes update`](https://machinemail.dev/docs/cli/commands/inboxes#inboxes-update)                | Update inbox                                          |
| [`pods create`](https://machinemail.dev/docs/cli/commands/pods#pods-create)                         | Create pod                                            |
| [`pods delete`](https://machinemail.dev/docs/cli/commands/pods#pods-delete)                         | Delete pod                                            |
| [`pods get`](https://machinemail.dev/docs/cli/commands/pods#pods-get)                               | Get pod                                               |
| [`pods list`](https://machinemail.dev/docs/cli/commands/pods#pods-list)                             | List pods                                             |
| [`pods update`](https://machinemail.dev/docs/cli/commands/pods#pods-update)                         | Update pod                                            |
| [`lists create`](https://machinemail.dev/docs/cli/commands/lists#lists-create)                      | Create list entry                                     |
| [`lists delete`](https://machinemail.dev/docs/cli/commands/lists#lists-delete)                      | Delete list entry                                     |
| [`lists get`](https://machinemail.dev/docs/cli/commands/lists#lists-get)                            | Get list entry                                        |
| [`lists list`](https://machinemail.dev/docs/cli/commands/lists#lists-list)                          | List the entries of an allow or block list            |
| [`suppressions create`](https://machinemail.dev/docs/cli/commands/suppressions#suppressions-create) | Add suppression                                       |
| [`suppressions delete`](https://machinemail.dev/docs/cli/commands/suppressions#suppressions-delete) | Remove suppression                                    |
| [`suppressions get`](https://machinemail.dev/docs/cli/commands/suppressions#suppressions-get)       | Get suppression                                       |
| [`suppressions list`](https://machinemail.dev/docs/cli/commands/suppressions#suppressions-list)     | List suppressions                                     |

## Domains

| Command                                                                                    | Summary                  |
| ------------------------------------------------------------------------------------------ | ------------------------ |
| [`domains connect`](https://machinemail.dev/docs/cli/commands/domains#domains-connect)     | Get Domain Connect setup |
| [`domains create`](https://machinemail.dev/docs/cli/commands/domains#domains-create)       | Create domain            |
| [`domains delete`](https://machinemail.dev/docs/cli/commands/domains#domains-delete)       | Delete domain            |
| [`domains get`](https://machinemail.dev/docs/cli/commands/domains#domains-get)             | Get domain               |
| [`domains list`](https://machinemail.dev/docs/cli/commands/domains#domains-list)           | List domains             |
| [`domains update`](https://machinemail.dev/docs/cli/commands/domains#domains-update)       | Update domain            |
| [`domains verify`](https://machinemail.dev/docs/cli/commands/domains#domains-verify)       | Verify domain            |
| [`domains zone-file`](https://machinemail.dev/docs/cli/commands/domains#domains-zone-file) | Get zone file            |

## Webhooks

| Command                                                                                                 | Summary                                           |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`webhooks create`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-create)                 | Create webhook                                    |
| [`webhooks delete`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-delete)                 | Delete webhook                                    |
| [`webhooks deliveries`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-deliveries)         | List deliveries                                   |
| [`webhooks get`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-get)                       | Get webhook                                       |
| [`webhooks headers`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-headers)               | Get webhook headers                               |
| [`webhooks list`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-list)                     | List webhooks                                     |
| [`webhooks replay`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-replay)                 | Replay delivery                                   |
| [`webhooks test`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-test)                     | Send test event                                   |
| [`webhooks update`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-update)                 | Update webhook                                    |
| [`webhooks update-headers`](https://machinemail.dev/docs/cli/commands/webhooks#webhooks-update-headers) | Update webhook headers                            |
| [`events get`](https://machinemail.dev/docs/cli/commands/events#events-get)                             | Get event                                         |
| [`events list`](https://machinemail.dev/docs/cli/commands/events#events-list)                           | List events                                       |
| [`events stream`](https://machinemail.dev/docs/cli/commands/events#events-stream)                       | Stream events as they happen (server-sent events) |

## Admin

| Command                                                                                                                  | Summary                                                                            |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| [`org get`](https://machinemail.dev/docs/cli/commands/org#org-get)                                                       | Get organization                                                                   |
| [`org members`](https://machinemail.dev/docs/cli/commands/org#org-members)                                               | List members                                                                       |
| [`org update`](https://machinemail.dev/docs/cli/commands/org#org-update)                                                 | Update organization                                                                |
| [`org usage`](https://machinemail.dev/docs/cli/commands/org#org-usage)                                                   | Get plan usage                                                                     |
| [`api-keys create`](https://machinemail.dev/docs/cli/commands/api-keys#api-keys-create)                                  | Create API key                                                                     |
| [`api-keys delete`](https://machinemail.dev/docs/cli/commands/api-keys#api-keys-delete)                                  | Delete API key                                                                     |
| [`api-keys get`](https://machinemail.dev/docs/cli/commands/api-keys#api-keys-get)                                        | Get API key                                                                        |
| [`api-keys list`](https://machinemail.dev/docs/cli/commands/api-keys#api-keys-list)                                      | List API keys                                                                      |
| [`api-keys update`](https://machinemail.dev/docs/cli/commands/api-keys#api-keys-update)                                  | Update API key                                                                     |
| [`agent-registrations delete`](https://machinemail.dev/docs/cli/commands/agent-registrations#agent-registrations-delete) | Revoke agent registration                                                          |
| [`agent-registrations get`](https://machinemail.dev/docs/cli/commands/agent-registrations#agent-registrations-get)       | Get agent registration                                                             |
| [`agent-registrations list`](https://machinemail.dev/docs/cli/commands/agent-registrations#agent-registrations-list)     | List agent registrations                                                           |
| [`metrics events`](https://machinemail.dev/docs/cli/commands/metrics#metrics-events)                                     | Query events                                                                       |
| [`metrics rates`](https://machinemail.dev/docs/cli/commands/metrics#metrics-rates)                                       | Query rates                                                                        |
| [`metrics usage`](https://machinemail.dev/docs/cli/commands/metrics#metrics-usage)                                       | Query usage                                                                        |
| [`health check`](https://machinemail.dev/docs/cli/commands/health#health-check)                                          | Check that the API is up (liveness)                                                |
| [`health ready`](https://machinemail.dev/docs/cli/commands/health#health-ready)                                          | Check that the API can serve requests (readiness)                                  |
| [`import agentmail`](https://machinemail.dev/docs/cli/commands/import#import-agentmail)                                  | Copy AgentMail settings (pods, domains, inboxes, webhooks, lists) into MachineMail |

## CLI

| Command                                                                                 | Summary                                                                  |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`open`](https://machinemail.dev/docs/cli/commands/utilities#open)                      | Open the dashboard in a browser                                          |
| [`completion`](https://machinemail.dev/docs/cli/commands/utilities#completion)          | Print a shell completion script (bash, zsh, fish)                        |
| [`version`](https://machinemail.dev/docs/cli/commands/utilities#version)                | Print the CLI version                                                    |
| [`auth login`](https://machinemail.dev/docs/cli/commands/auth#auth-login)               | Sign in with the browser (or an API key) and save the key to a profile   |
| [`auth logout`](https://machinemail.dev/docs/cli/commands/auth#auth-logout)             | Remove the stored key from a profile, and optionally revoke it           |
| [`auth me`](https://machinemail.dev/docs/cli/commands/auth#auth-me)                     | The credential as the API reports it (GET /v0/auth/me; whoami says more) |
| [`auth status`](https://machinemail.dev/docs/cli/commands/auth#auth-status)             | Show the key, profile and API in use, and check the key                  |
| [`auth whoami`](https://machinemail.dev/docs/cli/commands/auth#auth-whoami)             | Show the key, profile and API in use, and check the key                  |
| [`config get`](https://machinemail.dev/docs/cli/commands/config#config-get)             | Print the value of a config key in effect                                |
| [`config list`](https://machinemail.dev/docs/cli/commands/config#config-list)           | Print the config file, keys masked                                       |
| [`config path`](https://machinemail.dev/docs/cli/commands/config#config-path)           | Print the config file path                                               |
| [`config set`](https://machinemail.dev/docs/cli/commands/config#config-set)             | Set a config key                                                         |
| [`config unset`](https://machinemail.dev/docs/cli/commands/config#config-unset)         | Remove a config key (back to its default)                                |
| [`profiles delete`](https://machinemail.dev/docs/cli/commands/profiles#profiles-delete) | Delete a profile and its stored key                                      |
| [`profiles list`](https://machinemail.dev/docs/cli/commands/profiles#profiles-list)     | List profiles (keys masked)                                              |
| [`profiles use`](https://machinemail.dev/docs/cli/commands/profiles#profiles-use)       | Make a profile the current one                                           |

## More

| Command                                                                                                                | Summary                 |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| [`connected-apps delete`](https://machinemail.dev/docs/cli/commands/connected-apps#connected-apps-delete)              | Disconnect app          |
| [`connected-apps list`](https://machinemail.dev/docs/cli/commands/connected-apps#connected-apps-list)                  | List connected apps     |
| [`trusted-domains create`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-create)           | Create trusted domain   |
| [`trusted-domains delete`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-delete)           | Delete trusted domain   |
| [`trusted-domains get`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-get)                 | Get trusted domain      |
| [`trusted-domains list`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-list)               | List trusted domains    |
| [`trusted-domains preview`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-preview)         | Preview trusted domain  |
| [`trusted-domains suggestions`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-suggestions) | Suggest trusted domains |
| [`trusted-domains update`](https://machinemail.dev/docs/cli/commands/trusted-domains#trusted-domains-update)           | Update trusted domain   |