Agents CLI

The broadcast CLI is a lightweight command-line tool that wraps the Broadcast REST API. It’s a single bash script with no dependencies beyond curl and optionally jq.

Installation

Install the CLI with a single command:

curl -fsSL https://your-instance.com/agents/install | bash

This downloads the broadcast script to ~/.local/bin/broadcast and makes it executable. The install script also detects your shell and adds ~/.local/bin to your PATH if needed.

Authentication

After installation, authenticate with your API token:

broadcast login --token=YOUR_API_TOKEN --host=https://your-instance.com

This saves your credentials to ~/.config/broadcast/config with restricted permissions (chmod 600).

Verify Your Connection

broadcast whoami

This calls GET /api/v1/whoami and displays your token type, permissions, and channel information.

Discovering Capabilities

Use the prime command to see everything your token can do:

broadcast prime

This returns a full capabilities manifest including:

• Platform information (version, host, mode)
• Your token type and permissions
• Channel status (subscriber count, email server readiness)
• Available API endpoints grouped by resource
• Rate limit information
• Usage tips

Command Reference

Authentication & Discovery

Subscribers

Broadcasts

Sequences

Moving subscribers between sequences

A sequence with an entry tag enrolls every subscriber who gains that tag, and removes them when the tag is taken away. Their history in the sequence is kept, and gaining the tag again later does not restart it.

Setting an entry tag on a sequence does not enroll subscribers who already have that tag; it applies from then on. A tag also never removes a subscriber you added with broadcast sequences add, so direct and tag-based enrollment can be mixed safely.

For example, to move a customer from a trial sequence to a customer sequence when they pay:

# One time: give each sequence an entry tag
broadcast sequences update 11 --init-tag=trial
broadcast sequences update 12 --init-tag=customer

# At signup
broadcast subscribers create --email=jane@example.com --first-name=Jane --tag=trial

# When they pay
broadcast subscribers untag --email=jane@example.com --tag=trial
broadcast subscribers tag --email=jane@example.com --tag=customer

You can also move a subscriber directly with broadcast sequences remove 11 --email=jane@example.com followed by broadcast sequences add 12 --email=jane@example.com. Both print a result: enrolled, already_enrolled or removed. remove exits with code 3 if the subscriber was not in the sequence.

broadcast subscribers create --tag=X adds the tags to the subscriber’s existing ones, so running it for an address that is already subscribed never drops their other tags.

Templates and Design

Channel Settings

Requires Broadcast 2.46.0 or later, and a token with the Channel Settings permissions.

Segments

Topics

Opt-In Forms

Changing the thank-you message

After a signup, a form shows its post-submission view. thanks replaces that view with a heading and one or more text blocks, in the order you give them. Repeat --text for more paragraphs. Text is HTML and is shown as written.

With double opt-in, use it to tell new subscribers to click the confirmation link:

broadcast opt-in-forms thanks --all \
  --heading="One more step: check your email" \
  --text="We just sent you an email with a confirmation link. Click that link to start getting the newsletter." \
  --text="No email after a few minutes? Look in your spam, junk or promotions folder."

thanks is safe to run again: a form that already shows these blocks is not changed. --all reads the form list, so it needs jq or python3. It prints one line per form, {"id":15,"result":"updated"} or {"id":15,"result":"failed","exit":3}, continues after a failure, and exits with a non-zero code if any form failed. A/B variants are not in the form list; update one with thanks VARIANT_ID.

The API behind it is described in Opt-In Forms API.

Transactional Email

Email Servers

Webhook Endpoints

Autopilots

Suppressions

Any Endpoint

broadcast api METHOD PATH [--data=JSON] calls any endpoint and prints the response, for example broadcast api GET /api/v1/prime. Use it for anything the commands above do not cover.

Options for Every Command

• List commands take --page=N, --limit=N and --offset=N, and --param KEY=VALUE (repeatable) for any other filter the API takes. For example: broadcast subscribers list --param is_active=true --param "tags[]=vip".
• Create and update commands take --data with the request body exactly as the API expects it: --data='{"template":{"label":"Welcome"}}', --data=@template.json to read a file, or --data=- to read standard input. The API reference pages list every field.

The CLI uses channel tokens, so admin-only endpoints (users, the global suppression list, copying an email server to another channel) are not commands. Call them through the API.

General

The CLI is served by your own Broadcast instance, so after you upgrade Broadcast, run broadcast upgrade to pick up any new commands. It downloads the current script from https://your-instance.com/agents/cli (the host you logged in with) and installs it over the existing one.

Output Formats

By default, the CLI outputs JSON. For human-readable output, use the --format=table flag:

broadcast subscribers --format=table

Exit Codes

Configuration

The CLI stores its configuration at ~/.config/broadcast/config:

BROADCAST_HOST=https://your-instance.com
BROADCAST_TOKEN=your-api-token

This file is created with chmod 600 (owner read/write only) for security.

Using with AI Agents

The CLI is designed to be used by AI agents. When you paste the introduction message from the Agents dashboard into an agent like Claude Code, it can use the broadcast CLI to manage your email marketing automatically.

Example agent workflow:

Agent: Let me check your Broadcast status.
> broadcast status

Agent: You have 1,234 active subscribers. Let me create a newsletter draft.
> broadcast broadcasts create --subject="Weekly Update" --body="<h1>This Week</h1>..."

Agent: Draft created (ID: 42). Would you like me to send it?
> broadcast broadcasts send 42