Sendblue CLI
Overview
@sendblue/cli is a Node CLI that creates a Sendblue account, provisions an iMessage-enabled number, and sends messages. It is the fastest way to text from a shell, script, or Claude Code hook — no API client, no webhook server, no credentials in env vars. Credentials live at ~/.sendblue/credentials.json (mode 600) and Node.js 18+ is required.
When to Use This Skill
- Use when the user wants to text a phone number from a script, shell, hook, or agent turn (e.g. "text me when X finishes", "ping my phone", "notify on completion").
- Use when the user mentions
sendblue as a CLI/binary or asks to set up the @sendblue/cli package.
- Prefer this skill over [[sendblue-api]] when the work happens in a shell context, one-shot script, cron job, or agent hook.
- Reach for [[sendblue-api]] instead when writing application code that integrates Sendblue, receiving inbound webhooks, or needing features the CLI does not expose (send styles, reactions, group messages, status callbacks, media uploads).
How It Works
Step 1: Install
npm install -g @sendblue/cli # global, exposes `sendblue`
# or one-shot:
npx @sendblue/cli <command>
Step 2: Set up an account
sendblue setup runs interactively by default. For CI/scripts, run it in two phases — the first call sends an 8-digit verification code by email, the second consumes it.
sendblue setup --email you@example.com # sends code
sendblue setup --email you@example.com --code 12345678 \
--company my-co --contact +15551234567 # completes setup
| Flag |
Notes |
--email |
Email address |
--code |
8-digit verification code (from the email) |
--company |
Lowercase, hyphens/underscores, 3–64 chars |
--contact |
First contact, E.164 |
Step 3: Send messages
sendblue send +15551234567 'Hello from Sendblue!'
sendblue messages --inbound --limit 20
Phone numbers must be E.164 (+ + country code + digits, no spaces or dashes).
Step 4: Manage contacts and plan
On the free plan, a contact must text your Sendblue number once before outbound sends to that contact will work. After sendblue setup ... --contact +15551234567, have that contact send any text to the printed Sendblue number, then run sendblue contacts to confirm verification.
Command Reference
| Command |
Purpose |
sendblue setup |
Create account, verify email, set company name, add first contact |
sendblue login |
Log in to an existing account |
sendblue send <number> <message> |
Send an iMessage |
sendblue messages [--inbound|--outbound] [-n <number>] [-l <count>] |
List recent messages |
sendblue add-contact <number> |
Register a contact |
sendblue contacts |
List contacts and their verification status |
sendblue status |
Account/plan info |
sendblue whoami |
Show current credentials and verify validity |
Examples
Example 1: Notify when a long task finishes
long_running_thing && sendblue send +15551234567 "✅ done: $(date)"
Example 2: Read recent inbound for a specific contact
sendblue messages -n +15551234567 --inbound --limit 50
Example 3: Verify creds are good before a batch send
sendblue whoami || sendblue login
Example 4: Wire to a Claude Code Stop hook
To text yourself at the end of every agent turn, register a Stop hook in settings.json that shells out to sendblue send. Defer the actual hook wiring to [[update-config]] and the trigger logic to [[sendblue-notify]] — this skill only owns the CLI invocation.
Best Practices
- ✅ Use E.164 numbers everywhere.
+15551234567, never 5551234567 or (555) 123-4567.
- ✅ Run
sendblue whoami before unattended batches to fail fast on stale or missing creds.
- ✅ Re-run
setup as the same OS user that owns ~/.sendblue/credentials.json.
- ❌ Don't
sudo — it writes creds to root's home and the next non-sudo run won't see them.
- ❌ Don't embed creds in env vars when the CLI already reads them from the per-user credentials file.
Limitations
- Outbound-first: there is no built-in webhook server for inbound. Use [[sendblue-api]] webhooks for full inbound handling.
- The CLI does not expose send styles/effects, reactions, group messages, status callbacks, media uploads, or the contacts API beyond basic CRUD. Reach for the HTTP API for those.
- Free-plan accounts require recipient verification before outbound sends succeed.
Security & Safety Notes
- Credentials are written to
~/.sendblue/credentials.json with mode 600. Treat that file like an API key — do not commit it, do not copy it across machines without the same posture.
- Treat every outbound send, contact setup, login, or account setup action as state-changing. Preview the recipient, message body, and account/email target, then wait for explicit user confirmation before running it.
- Run the CLI as the OS user that owns the credentials file.
sudo writes a separate copy under root's home and silently desyncs.
- Outbound messages to phone numbers are not free of consequence — wire
sendblue send into hooks or loops only after gating on duration or success conditions to avoid spamming the recipient.
- Verification codes arrive by email; treat the address you registered with as a recovery factor for the account.
Common Pitfalls
- E.164 only.
5551234567 or (555) 123-4567 will fail — always +15551234567.
- Free-plan unverified contacts. Outbound to a contact that hasn't texted in first returns an error — have them text your Sendblue number once, then confirm with
sendblue contacts.
- Two-step setup in non-interactive mode.
--email alone only sends the code; you must run a second invocation with --code and the rest of the flags to finish.
- Credentials are per-user.
~/.sendblue/credentials.json is owner-only (600). Don't sudo and pollute root's home — re-running as the same user that ran setup is what works.
Related Skills
@sendblue-api — HTTP/JSON alternative for application code, webhooks, and features the CLI does not expose.@sendblue-notify — Patterns and copy rules for "text me when X is done" workflows that sit on top of this CLI.@update-config — Wires sendblue send into Claude Code hooks (Stop, Notification) without owning the message logic.
Links
Source: sickn33/agentic-awesome-skills → skills/sendblue/sendblue-cli/SKILL.md
1---2name: sendblue-cli3description: Send iMessage and SMS from the shell via the @sendblue/cli npm package — outbound sends, contact management, and account setup with no API client or webhook server required.4---5
6
7# Sendblue CLI
8
9## Overview
10
11`@sendblue/cli` is a Node CLI that creates a Sendblue account, provisions an iMessage-enabled number, and sends messages. It is the fastest way to text from a shell, script, or Claude Code hook — no API client, no webhook server, no credentials in env vars. Credentials live at `~/.sendblue/credentials.json` (mode `600`) and Node.js 18+ is required.
12
13## When to Use This Skill
14
15- Use when the user wants to text a phone number from a script, shell, hook, or agent turn (e.g. "text me when X finishes", "ping my phone", "notify on completion").
16- Use when the user mentions `sendblue` as a CLI/binary or asks to set up the `@sendblue/cli` package.
17- Prefer this skill over [[sendblue-api]] when the work happens in a shell context, one-shot script, cron job, or agent hook.
18- Reach for [[sendblue-api]] instead when writing application code that integrates Sendblue, receiving inbound webhooks, or needing features the CLI does not expose (send styles, reactions, group messages, status callbacks, media uploads).
19
20## How It Works
21
22### Step 1: Install
23
24```bash
25npm install -g @sendblue/cli # global, exposes `sendblue`
26# or one-shot:
27npx @sendblue/cli <command>
28```
29
30### Step 2: Set up an account
31
32`sendblue setup` runs interactively by default. For CI/scripts, run it in two phases — the first call sends an 8-digit verification code by email, the second consumes it.
33
34```bash
35sendblue setup --email you@example.com # sends code
36sendblue setup --email you@example.com --code 12345678 \
37 --company my-co --contact +15551234567 # completes setup
38```
39
40| Flag | Notes |
41|---|---|
42| `--email` | Email address |
43| `--code` | 8-digit verification code (from the email) |
44| `--company` | Lowercase, hyphens/underscores, 3–64 chars |
45| `--contact` | First contact, E.164 |
46
47### Step 3: Send messages
48
49```bash
50sendblue send +15551234567 'Hello from Sendblue!'
51sendblue messages --inbound --limit 20
52```
53
54Phone numbers must be E.164 (`+` + country code + digits, no spaces or dashes).
55
56### Step 4: Manage contacts and plan
57
58On the free plan, **a contact must text your Sendblue number once before outbound sends to that contact will work**. After `sendblue setup ... --contact +15551234567`, have that contact send any text to the printed Sendblue number, then run `sendblue contacts` to confirm verification.
59
60## Command Reference
61
62| Command | Purpose |
63|---|---|
64| `sendblue setup` | Create account, verify email, set company name, add first contact |
65| `sendblue login` | Log in to an existing account |
66| `sendblue send <number> <message>` | Send an iMessage |
67| `sendblue messages [--inbound\|--outbound] [-n <number>] [-l <count>]` | List recent messages |
68| `sendblue add-contact <number>` | Register a contact |
69| `sendblue contacts` | List contacts and their verification status |
70| `sendblue status` | Account/plan info |
71| `sendblue whoami` | Show current credentials and verify validity |
72
73## Examples
74
75### Example 1: Notify when a long task finishes
76
77```bash
78long_running_thing && sendblue send +15551234567 "✅ done: $(date)"
79```
80
81### Example 2: Read recent inbound for a specific contact
82
83```bash
84sendblue messages -n +15551234567 --inbound --limit 50
85```
86
87### Example 3: Verify creds are good before a batch send
88
89```bash
90sendblue whoami || sendblue login
91```
92
93### Example 4: Wire to a Claude Code `Stop` hook
94
95To text yourself at the end of every agent turn, register a `Stop` hook in `settings.json` that shells out to `sendblue send`. Defer the actual hook wiring to [[update-config]] and the trigger logic to [[sendblue-notify]] — this skill only owns the CLI invocation.
96
97## Best Practices
98
99- ✅ **Use E.164 numbers everywhere.** `+15551234567`, never `5551234567` or `(555) 123-4567`.
100- ✅ **Run `sendblue whoami` before unattended batches** to fail fast on stale or missing creds.
101- ✅ **Re-run `setup` as the same OS user** that owns `~/.sendblue/credentials.json`.
102- ❌ **Don't `sudo`** — it writes creds to root's home and the next non-sudo run won't see them.
103- ❌ **Don't embed creds in env vars** when the CLI already reads them from the per-user credentials file.
104
105## Limitations
106
107- Outbound-first: there is no built-in webhook server for inbound. Use [[sendblue-api]] webhooks for full inbound handling.
108- The CLI does not expose send styles/effects, reactions, group messages, status callbacks, media uploads, or the contacts API beyond basic CRUD. Reach for the HTTP API for those.
109- Free-plan accounts require recipient verification before outbound sends succeed.
110
111## Security & Safety Notes
112
113- Credentials are written to `~/.sendblue/credentials.json` with mode `600`. Treat that file like an API key — do not commit it, do not copy it across machines without the same posture.
114- Treat every outbound send, contact setup, login, or account setup action as state-changing. Preview the recipient, message body, and account/email target, then wait for explicit user confirmation before running it.
115- Run the CLI as the OS user that owns the credentials file. `sudo` writes a separate copy under root's home and silently desyncs.
116- Outbound messages to phone numbers are not free of consequence — wire `sendblue send` into hooks or loops only after gating on duration or success conditions to avoid spamming the recipient.
117- Verification codes arrive by email; treat the address you registered with as a recovery factor for the account.
118
119## Common Pitfalls
120
121- **E.164 only.** `5551234567` or `(555) 123-4567` will fail — always `+15551234567`.
122- **Free-plan unverified contacts.** Outbound to a contact that hasn't texted in first returns an error — have them text your Sendblue number once, then confirm with `sendblue contacts`.
123- **Two-step setup in non-interactive mode.** `--email` alone only sends the code; you must run a second invocation with `--code` and the rest of the flags to finish.
124- **Credentials are per-user.** `~/.sendblue/credentials.json` is owner-only (`600`). Don't `sudo` and pollute root's home — re-running as the same user that ran `setup` is what works.
125
126## Related Skills
127
128- `@sendblue-api` — HTTP/JSON alternative for application code, webhooks, and features the CLI does not expose.
129- `@sendblue-notify` — Patterns and copy rules for "text me when X is done" workflows that sit on top of this CLI.
130- `@update-config` — Wires `sendblue send` into Claude Code hooks (`Stop`, `Notification`) without owning the message logic.
131
132## Links
133
134- README & full flag reference: <https://github.com/sendblue-api/sendblue-cli>
135- Sendblue: <https://sendblue.com>
136- API docs (deeper protocol details): <https://docs.sendblue.com>
137
138---
139
140**Source:** [`sickn33/agentic-awesome-skills`](https://github.com/sickn33/agentic-awesome-skills) → `skills/sendblue/sendblue-cli/SKILL.md`
sickn33