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