# CLI

> Source: https://developers.anymail.watch/cli/

`anymail` is a command line client for the REST API. It has no dependencies beyond Node.js 20 or later, prints tables for people and JSON for scripts, and works with the same [API tokens](/authentication/) as the API.

## Install

Install it from npm:

```bash
npm install -g anymail-cli
anymail --help
```

## Log in

```bash
anymail login --token sgn_…
```

The CLI checks the token with `GET /workspaces` before it saves it to `~/.config/anymail/config.json` with permissions `600`. In CI, skip the file and set the token in the environment:

| Variable | Meaning |
|---|---|
| `ANYMAIL_API_TOKEN` | The token. It takes precedence over the saved one. |
| `ANYMAIL_API_URL` | The base URL. Default `https://app.anymail.watch`. |

A read only token is enough for `list`, `search` and `stats`.

## Commands

| Command | What it does |
|---|---|
| `anymail campaigns list [--status <status>]` | Campaigns with status and progress. `<status>` is `draft`, `active`, `paused` or `completed`. |
| `anymail campaigns create --name "Q4 outbound" [--mailbox <id>]…` | A new draft. Repeat `--mailbox` for several mailboxes. |
| `anymail campaigns start <id>` | Start a draft or resume a paused campaign. This sends email. |
| `anymail campaigns stop <id>` | End a campaign for good. |
| `anymail prospects add <email> [--first-name] [--last-name] [--company] [--campaign <id>]` | Create a prospect, and enrol it when `--campaign` is set. |
| `anymail prospects search <text>` | Search by email, name or company. |
| `anymail stats <campaign-id>` | The totals of a campaign. |
| `anymail api <METHOD> <path> [--data '<json>']` | Any endpoint, for example `anymail api GET /v1/domains`. |

Add `--json` to print the raw response. For lists, `--json` prints only the `data` array, so `anymail campaigns list --json | jq length` counts campaigns.

```bash
anymail prospects add ada@example.com --first-name Ada --company "Example Ltd" --campaign 3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
anymail stats 3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d --json
```

An API error prints `HTTP <status> <METHOD> <path>: <message>` and exits with code `1`. The token never appears in the output.

## Related

- [Authentication](/authentication/)
- [Campaigns](/campaigns/)
- [OpenAPI and Postman](/openapi/)