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.
Note
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
| Command | Description |
|---|---|
broadcast login --token=X --host=Y |
Save credentials and verify connection |
broadcast whoami |
Show token info and permissions |
broadcast prime |
Show full capabilities manifest |
broadcast status |
Show channel health and readiness |
Subscribers
| Command | Description |
|---|---|
broadcast subscribers |
List subscribers |
broadcast subscribers find --email=X |
Find a subscriber by email |
broadcast subscribers create --email=X |
Create a new subscriber |
broadcast subscribers tag --email=X --tag=Y |
Add a tag to a subscriber |
Broadcasts
| Command | Description |
|---|---|
broadcast broadcasts |
List broadcasts |
broadcast broadcasts show ID |
Show broadcast details |
broadcast broadcasts create --subject=X --body=Y |
Create a draft broadcast |
broadcast broadcasts send ID |
Send a broadcast |
broadcast broadcasts stats ID |
Show broadcast statistics |
Sequences
| Command | Description |
|---|---|
broadcast sequences |
List sequences |
broadcast sequences show ID |
Show sequence details |
General
| Command | Description |
|---|---|
broadcast help |
Show command reference |
Output Formats
By default, the CLI outputs JSON. For human-readable output, use the --format=table flag:
broadcast subscribers --format=table
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Authentication error |
| 2 | Resource not found |
| 3 | Validation error |
| 4 | Server error |
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
