> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and configure the Sendmux CLI for management, mailbox, and sending workflows.

Use the `sendmux` CLI when you want terminal access to the same Management, Mailbox, and Sending API surfaces exposed by the SDKs.

<Info>
  Sending commands accept a send-capable `smx_mbx_` key or owner-approved
  Sending-resource `smx_agent_` token. Mailbox commands accept `smx_mbx_` keys
  or scoped `smx_agent_` tokens. Management commands require team-scoped
  `smx_root_` keys.
</Info>

## Install

On Linux, install the CLI from the <a href="https://snapcraft.io/sendmux" rel="nofollow noopener noreferrer" target="_blank">Snap Store</a>.

```bash theme={null}
sudo snap install sendmux
```

On macOS or Linux, you can also install it with Homebrew.

```bash theme={null}
brew install sendmux/tap/sendmux
```

You can also install it from npm.

```bash theme={null}
npm install -g @sendmux/cli
```

Check the installed command.

```bash theme={null}
sendmux --version
sendmux --help
```

## Configure profiles

Save API keys as local CLI profiles so you do not pass a key on every command.

<CodeGroup>
  ```bash Mailbox profile theme={null}
  sendmux profiles:set mailbox \
    --api-key "$SENDMUX_MAILBOX_KEY" \
    --default
  ```

  ```bash Management profile theme={null}
  sendmux profiles:set management \
    --api-key "$SENDMUX_ROOT_KEY"
  ```
</CodeGroup>

The CLI stores profile configuration locally with restricted file permissions. `profiles:list --verbose` and `profiles:show` mask saved keys.

```bash theme={null}
sendmux profiles:list
sendmux profiles:list --verbose
sendmux profiles:show management
```

## Authentication order

Every API command resolves credentials in this order:

1. `--api-key`
2. `SENDMUX_API_KEY`
3. `--profile`
4. `SENDMUX_PROFILE`
5. the configured default profile

`--base-url` overrides the API base URL for one command. `SENDMUX_BASE_URL` overrides it for the current shell. A profile can also store a base URL override.

Before running the API call, the CLI checks that the key prefix matches the command surface. A management command fails early when it receives a mailbox-compatible key, and sending commands fail early when they receive a root key. Mailbox commands accept `smx_mbx_` keys and scoped `smx_agent_` tokens. API permissions still apply, so a pre-claim `smx_agent_` token cannot send email.

## Run commands

Commands use colon-separated names.

<CodeGroup>
  ```bash Sending theme={null}
  sendmux sending:send \
    --profile mailbox \
    --body '{"from":{"email":"sender@example.com"},"to":{"email":"recipient@example.com"},"subject":"Hello","text_body":"Sent with the Sendmux CLI"}' \
    --idempotency-key send-cli-001
  ```

  ```bash Mailbox theme={null}
  sendmux mailbox:messages:list \
    --profile mailbox \
    --query limit=25
  ```

  ```bash Management theme={null}
  sendmux management:mailboxes:list \
    --profile management \
    --query limit=25
  ```
</CodeGroup>

Pass request bodies inline with `--body` or from a file with `--body-file`.

```bash theme={null}
sendmux management:create-mailbox \
  --profile management \
  --body-file ./mailbox.json \
  --idempotency-key create-mailbox-001
```

Pass parameters with repeatable `name=value` flags:

* `--path name=value` for path parameters.
* `--query name=value` for query parameters.
* `--header name=value` for supported headers.

Typed values are validated before the request is sent. Unknown parameter names fail with the supported names for that command.

## Output

Without `--json`, API commands print formatted JSON for easy reading. Use `--json` when another process needs machine-readable output from the CLI.

```bash theme={null}
sendmux management:mailboxes:list --profile management --json
```

Text responses return `{ "text": "..." }` with `--json`. Binary responses return base64 data and `byte_length`.

## Request safety flags

Use the dedicated safety flags when the generated command supports the corresponding header:

| Flag                | Header            |
| ------------------- | ----------------- |
| `--idempotency-key` | `Idempotency-Key` |
| `--if-match`        | `If-Match`        |
| `--if-none-match`   | `If-None-Match`   |

The CLI rejects these flags on commands whose API operation does not accept the matching header.

## Command reference

The CLI command set is generated from the public API surfaces. Run `sendmux --help` to see the current topics, `sendmux <topic> --help` to browse a surface, and `sendmux <command> --help` for the flags supported by one command.

For example:

```bash theme={null}
sendmux sending --help
sendmux mailbox --help
sendmux management --help
sendmux sending:send --help
```

## Next steps

<CardGroup cols={2}>
  <Card title="SDK overview" icon="code" href="/docs/sdks">
    Choose package-managed clients for application code.
  </Card>

  <Card title="API keys" icon="key" href="/docs/guides/api-keys">
    Create scoped credentials before configuring CLI profiles.
  </Card>

  <Card title="Mailbox API" icon="inbox" href="/docs/mailbox-api/introduction">
    Review the API used by mailbox commands.
  </Card>

  <Card title="Management API" icon="chart-line" href="/docs/api/introduction">
    Review the API used by management commands.
  </Card>
</CardGroup>