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

# CLI

> Install and use the official Mermail CLI for Sold API and MCP automation.

The official Mermail CLI exposes all **62 Sold API business operations** with deterministic output for humans, scripts, CI jobs, and coding agents.

## Install

Until the package is on the public npm registry, install from GitHub:

```bash theme={null}
npm install -g github:Nudgen-Marketing/mermail-cli
# after npm publish: npm install -g mermail-cli
```

Or run a command without a global installation:

```bash theme={null}
npx --yes github:Nudgen-Marketing/mermail-cli --help
```

Node.js 22 or newer is required.

## Authenticate

Create a project key in **Settings → API Keys**, then export it in the process that launches the CLI:

```bash theme={null}
export MERMAIL_API_KEY="sk-proj-your-key"
```

The CLI does not store credentials and does not collect telemetry. Prefer the environment variable over `--api-key`, which may remain in shell history or process listings.

```bash theme={null}
mermail doctor
mermail auth check
```

`doctor` checks local configuration and public discovery without API credits. `auth check` calls the Sold API and consumes one read credit.

## Command structure

Commands follow `mermail <resource> <action> [flags]`:

`--mailbox-id` accepts the mailbox `public_id` (UUID), hosted alias id, or current email. Prefer `public_id` from `mermail mailboxes list`.

```bash theme={null}
mermail workspaces list
mermail mailboxes list --format table
mermail emails list --mailbox-id MAILBOX_PUBLIC_ID
mermail usage credits --workspace-id WORKSPACE_ID
```

Run `mermail --help`, `mermail <resource> --help`, or `mermail <resource> <action> --help` for the exact flags.

### Send email

```bash theme={null}
mermail emails send \
  --mailbox-id MAILBOX_PUBLIC_ID \
  --to recipient@example.com \
  --from agent@mermail.app \
  --subject "Hello" \
  --text "Hello from Mermail"
```

### Complex request bodies

Common fields have typed flags. Nested or complete bodies can use JSON, a file, or stdin:

```bash theme={null}
mermail triagers create --mailbox-id MAILBOX_ID --data-file triager.json
printf '%s' '{"name":"Support"}' | \
  mermail folders create --mailbox-id MAILBOX_ID --data-file -
```

Typed flags override the same fields supplied in JSON. `--data` and `--data-file` cannot be used together.

## Output formats

JSON is the stable default. Data is written to stdout; diagnostics and errors are written to stderr.

| Format             | Use                                        |
| ------------------ | ------------------------------------------ |
| `json`             | Scripts and agents; default                |
| `yaml`             | Human-readable structured output           |
| `pretty` / `table` | Interactive inspection                     |
| `raw`              | Text or explicitly requested binary output |

```bash theme={null}
mermail mailboxes list --format json | jq '.[].email'
mermail attachments download \
  --mailbox-id MAILBOX_ID \
  --email-id EMAIL_ID \
  --attachment-id ATTACHMENT_ID \
  --output-file attachment.pdf
```

## Destructive actions

Delete, remove, bulk-delete, and empty-trash commands prompt in an interactive terminal. Non-interactive automation must pass `--yes`:

```bash theme={null}
mermail emails delete \
  --mailbox-id MAILBOX_ID \
  --email-id EMAIL_ID \
  --permanent \
  --yes
```

<Warning>
  Verify exact resource IDs before adding `--yes`. The CLI never retries write, send, or delete operations automatically. `Idempotency-Key` protects credit accounting but does not guarantee that every business operation is executed only once.
</Warning>

## MCP checks

Verify that the hosted MCP server initializes and exposes exactly 63 tools:

```bash theme={null}
mermail mcp check
mermail mcp tools --format table
```

For controlled staging tests only:

```bash theme={null}
MERMAIL_BASE_URL=https://console-staging.mermail.app mermail mcp check
```

## Exit codes

|  Code | Meaning                                       |
| ----: | --------------------------------------------- |
|   `0` | Success                                       |
|   `1` | API, network, or runtime failure              |
|   `2` | Invalid command, flag, or payload             |
|   `3` | Missing, invalid, expired, or revoked API key |
|   `4` | Destructive confirmation required             |
| `130` | Cancelled or interrupted                      |

Common API statuses remain available in JSON errors: `402` credits exhausted, `403` workspace/plan denial, and `429` RPM exceeded.

## Related

<CardGroup cols={2}>
  <Card title="Skills" icon="puzzle-piece" href="/ai/skills">
    Give coding agents the dedicated `mermail-cli` workflow.
  </Card>

  <Card title="MCP" icon="plug" href="/ai/mcp">
    Use direct Streamable HTTP tool calling.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Create and protect project API keys.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Review request and response schemas.
  </Card>
</CardGroup>