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

# CLI reference

> Every subscriber command and its options.

The CLI lets you do everything from your terminal. Run `subscriber` with no arguments to open the [TUI](https://docs.subscriber.dev/tui.md), or add `--help` to any command to see its options.

```bash theme={null}
npm install -g @subscriber.dev/cli
```

It needs Node.js 22.12 or later.

## Options most commands share

| Option | Description |
| - | - |
| `--environment <id>` | Run against this environment instead of the current one. |
| `--workspace <id>` | Run against this workspace instead of the current one. |
| `--json` | Print JSON, for scripts and agents. |
| `--limit <n>`, `--offset <n>` | Page through lists. `--limit` is 1 to 100. |

Options that take a file, such as `--file`, accept `-` to read from stdin.

## Account

| Command | Description |
| - | - |
| `login` | Sign in through the browser. `--base-url` and `--app-url` point at a [self-hosted](https://docs.subscriber.dev/self-hosting.md) server. |
| `logout` | Sign out and forget the saved session. In the TUI, press `l` on My Account. |
| `whoami` | Show whether you're signed in, the API URL, and the current workspace and environment. |
| `users get` | Show your account. |
| `users update` | Change your `--name` or `--image`. |
| `agents list` | List the AI agents you've connected through [MCP](https://docs.subscriber.dev/mcp.md) sign-in. |
| `agents disconnect <clientId>` | Disconnect an agent. It loses access straight away. |

## API keys

API keys are for your app to call the [REST API](https://docs.subscriber.dev/api-reference/introduction.md#authentication). Each belongs to one environment.

| Command | Description |
| - | - |
| `keys create <name>` | Create a key and print it. It's only shown once. `--access limited` (the default) can trigger workflows and create or update subscribers; `--access full` can do everything a key can. Or pick scopes with `--scope <scope...>`. |
| `keys list` | List keys, with the first characters of each, their scopes and when they were last used. |
| `keys revoke <keyId>` | Revoke a key. Requests made with it fail straight away. |

## Workspaces and environments

| Command | Description |
| - | - |
| `workspaces list` | List your workspaces. |
| `workspaces create <name>` | Create a workspace. |
| `workspaces use <workspaceId>` | Make it the current workspace. |
| `workspaces update --postal-address <address>` | Set the postal address shown in every email footer. See [Postal address](https://docs.subscriber.dev/sending.md#postal-address). |
| `environments list` | List the current workspace's environments. |
| `environments create <name>` | Create an environment, such as staging. |
| `environments use <environmentId>` | Make it the current environment. |

## Subscribers

See [Subscribers](https://docs.subscriber.dev/subscribers.md).

| Command | Description |
| - | - |
| `subscribers list` | List subscribers. Filter with `--email`, `--external-id`, `--search <text>`, `--opted-in` or `--opted-out`. |
| `subscribers get <subscriberId>` | Show one subscriber. |
| `subscribers create` | Add a subscriber with `--email`, `--external-id`, `--first-name`, `--last-name`, `--name`, `--phone` and `--attributes <json>`. |
| `subscribers update <subscriberId>` | Change the fields you pass, using the same options as `create`. `--attributes` replaces all existing attributes. |
| `subscribers bulk --file <path>` | Create or update up to 500 subscribers from a JSON file. |
| `subscribers tag <subscriberId>` | `--add <tag>` or `--remove <tag>`. |
| `subscribers update-preferences <subscriberId>` | `--opted-in` or `--opted-out`. |
| `subscribers delete <subscriberId>` | Delete a subscriber. |

## Workflows

See [Workflows](https://docs.subscriber.dev/workflows.md).

| Command | Description |
| - | - |
| `workflows list` | List workflows. `--type automation` or `--type broadcast` filters them. |
| `workflows get <workflowId>` | Show a workflow and its steps. |
| `workflows edit <workflowId>` | Open the workflow's emails in the [web editor](https://docs.subscriber.dev/workflows.md#editing-emails-in-the-browser). |
| `workflows create --file <path>` | Create a workflow from a JSON file. |
| `workflows update <workflowId> --file <path>` | Change the fields in the file. If it includes `steps`, they replace all existing steps. |
| `workflows delete <workflowId>` | Delete a workflow. |
| `workflows test <workflowId>` | Send yourself one of the workflow's emails, with `[Test]` before the subject, without creating a subscriber or a run. `--step <n>` picks the step, counting from 1 (defaults to the first email), `--to <email>` sends it to someone else, and `--data <json>` fills in [template variables](https://docs.subscriber.dev/templates.md#variables). |
| `workflows trigger <key>` | Start a workflow for one subscriber, chosen by `--email`, `--external-id` or `--subscriber-id`. `--payload <json>` adds [template variables](https://docs.subscriber.dev/templates.md#variables). |
| `workflows runs <workflowId>` | List a workflow's runs. |
| `workflows run-history` | List runs across every workflow. |

## Images and videos

| Command | Description |
| - | - |
| `uploads image <path>` | Upload a PNG, JPEG, GIF or WebP image, up to 5 MB, and print its URL to use in an email. |
| `uploads video <url>` | Turn a YouTube, Vimeo or Loom link into a thumbnail with a play button, and print the HTML to put in an email. |

## Broadcasts

See [Broadcasts](https://docs.subscriber.dev/broadcasts.md).

| Command | Description |
| - | - |
| `workflows broadcast <workflowId> --audience <path>` | Send a workflow to everyone matching an [audience](https://docs.subscriber.dev/broadcasts.md#audiences). `--send-over-hours <n>` spreads it over up to 168 hours. `--allow-over-plan` sends even if it goes past your plan's subscriber limit. |
| `workflows broadcasts <workflowId>` | List a workflow's broadcasts. |
| `workflows broadcast-pause <workflowId> <broadcastId>` | Hold every send that hasn't gone out yet. |
| `workflows broadcast-resume <workflowId> <broadcastId>` | Carry on a paused broadcast. |
| `workflows broadcast-cancel <workflowId> <broadcastId>` | Stop every send that hasn't gone out yet. This can't be undone. |
| `workflows broadcast-redispatch <workflowId> <broadcastId>` | Retry anyone a broadcast didn't reach, such as after an error. People already sent to are skipped. |

## Integrations

See [Integrations](https://docs.subscriber.dev/integrations/overview.md).

| Command | Description |
| - | - |
| `integrations list` | List connected integrations. |
| `integrations get <type>` | Show one, such as `smtp`. |
| `integrations set <type> --body <json>` | Connect or update `smtp`, `cloudflare` or `stripe`. |
| `integrations set-primary <type>` | Try this email provider first. |
| `integrations events` | List events from Stripe and what happened to each. `--source stripe` filters them. |
| `integrations remove <type>` | Disconnect an integration. |

## Other commands

| Command | Description |
| - | - |
| `analytics` | Subscriber counts, opt-outs, sends and bounces for an environment. `--days <n>` sets the window for new and opted-out counts (default 30); send and bounce totals are all-time. |
| `billing` | Show your plan and usage. See [Plans and limits](https://docs.subscriber.dev/plans.md). |
| `billing upgrade <plan>` | Start or change a paid plan: `starter`, `growth`, `scale`, `pro` or `business`. `--annual` or `--monthly`. |
| `billing portal` | Open Stripe to manage your card and invoices, or cancel. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.