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

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

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.

…