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

) 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

bash

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.

bash

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

bash

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

bash

long_running_thing && sendblue send +15551234567 "✅ done: $(date)"

Example 2: Read recent inbound for a specific contact

bash

sendblue messages -n +15551234567 --inbound --limit 50

Example 3: Verify creds are good before a batch send

bash

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.
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.

sendblue-cli

NPX Install

Tags

SKILL.md Content

Sendblue CLI

Overview

When to Use This Skill

How It Works

Step 1: Install

Step 2: Set up an account

Step 3: Send messages

Step 4: Manage contacts and plan

Command Reference

Examples

Example 1: Notify when a long task finishes

Example 2: Read recent inbound for a specific contact

Example 3: Verify creds are good before a batch send

Example 4: Wire to a Claude Code
`Stop`
hook

Best Practices

Limitations

Security & Safety Notes

Common Pitfalls

Related Skills

Links