sendblue-cli

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 [email protected]                                       # sends code
sendblue setup --email [email protected] --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

• README & full flag reference: https://github.com/sendblue-api/sendblue-cli
• Sendblue: https://sendblue.com
• API docs (deeper protocol details): https://docs.sendblue.com