sendblue-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

@sendblue/cli

是一款Node CLI工具，可创建Sendblue账户、开通支持iMessage的号码并发送消息。这是从Shell、脚本或Claude Code钩子发送短信最快的方式——无需API客户端、无需Webhook服务器、无需在环境变量中存储凭据。凭据存储在

~/.sendblue/credentials.json

（权限模式

）中，且需要Node.js 18+版本。

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

当用户希望从脚本、Shell、钩子或Agent流程中向电话号码发送短信时使用（例如“X完成时发短信通知我”、“给我手机发提醒”、“完成时通知”）。
当用户提到
```
sendblue
```
作为CLI/二进制工具，或要求设置
```
@sendblue/cli
```
包时使用。
当工作场景为Shell环境、一次性脚本、定时任务或Agent钩子时，优先使用该工具而非[[sendblue-api]]。
当编写集成Sendblue的应用代码、接收入站Webhook，或需要CLI未提供的功能（如发送样式、消息反应、群组消息、状态回调、媒体上传）时，请改用[[sendblue-api]]。

How It Works

使用流程

Step 1: Install

步骤1：安装

bash

npm install -g @sendblue/cli       # global, exposes `sendblue`

bash

npm install -g @sendblue/cli       # 全局安装，暴露`sendblue`命令

or one-shot:

或单次使用：

npx @sendblue/cli <command>

undefined

npx @sendblue/cli <command>

undefined

Step 2: Set up an account

步骤2：设置账户

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

sendblue setup

默认以交互式运行。对于CI/脚本场景，分两个阶段运行——第一次调用会通过邮箱发送8位验证码，第二次调用输入验证码完成设置。

bash

sendblue setup --email you@example.com                                       # 发送验证码
sendblue setup --email you@example.com --code 12345678 \
               --company my-co --contact +15551234567                        # 完成设置

标志	说明
`--email`	邮箱地址
`--code`	8位验证码（来自邮箱）
`--company`	小写，允许连字符/下划线，长度3–64字符
`--contact`	首个联系人号码，需符合E.164格式

Step 3: Send messages

步骤3：发送消息

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

bash

sendblue send +15551234567 'Hello from Sendblue!'
sendblue messages --inbound --limit 20

电话号码必须符合E.164格式（

+ 国家代码 + 数字，无空格或连字符）。

Step 4: Manage contacts and plan

步骤4：管理联系人和套餐

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.

在免费套餐下，联系人必须先向你的Sendblue号码发送一条短信，才能接收你发送的外发消息。执行

sendblue setup ... --contact +15551234567

后，让该联系人向显示的Sendblue号码发送任意短信，然后运行

sendblue contacts

确认验证状态。

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

命令	用途
`sendblue setup`	创建账户、验证邮箱、设置公司名称、添加首个联系人
`sendblue login`	登录现有账户
`sendblue send <number> <message>`	发送iMessage
`sendblue messages [--inbound\|--outbound] [-n <number>] [-l <count>]`	列出近期消息
`sendblue add-contact <number>`	注册联系人
`sendblue contacts`	列出联系人及其验证状态
`sendblue status`	账户/套餐信息
`sendblue whoami`	显示当前凭据并验证有效性

Examples

示例

Example 1: Notify when a long task finishes

示例1：长任务完成时通知

bash

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

bash

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

Example 2: Read recent inbound for a specific contact

示例2：读取特定联系人的近期入站消息

bash

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

bash

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

Example 3: Verify creds are good before a batch send

示例3：批量发送前验证凭据有效性

bash

sendblue whoami || sendblue login

bash

sendblue whoami || sendblue login

Example 4: Wire to a Claude Code

Stop

hook

示例4：接入Claude Code

Stop

钩子

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.

要在每次Agent流程结束时给自己发短信，在

settings.json

中注册一个调用

sendblue send

的

Stop

钩子。具体的钩子配置逻辑请参考[[update-config]]，触发逻辑请参考[[sendblue-notify]]——本工具仅负责CLI调用部分。

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.

✅ 全程使用E.164格式号码。使用
```
+15551234567
```
，切勿使用
```
5551234567
```
或
```
(555) 123-4567
```
。
✅ 无人值守批量发送前运行
sendblue whoami
，以便在凭据过期或缺失时快速失败。
✅ 以拥有
~/.sendblue/credentials.json
文件的操作系统用户身份重新运行
setup
。
❌ 不要使用
sudo
——这会将凭据写入root用户的主目录，后续非sudo运行将无法读取。
❌ 不要将凭据嵌入环境变量——CLI已从每个用户的凭据文件中读取凭据。

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.

以外发为主：没有内置的入站Webhook服务器。如需完整的入站处理，请使用[[sendblue-api]]的Webhook功能。
CLI未提供发送样式/特效、消息反应、群组消息、状态回调、媒体上传或基础CRUD之外的联系人API功能。如需这些功能，请使用HTTP API。
免费套餐账户要求收件人先验证，才能成功发送外发消息。

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.

凭据被写入
```
~/.sendblue/credentials.json
```
，权限模式为
```
600
```
。请像对待API密钥一样对待该文件——不要提交到代码仓库，不要在不同机器间随意复制，除非采取相同的安全措施。
以拥有凭据文件的操作系统用户身份运行CLI。使用
```
sudo
```
会在root用户主目录下写入单独的凭据副本，导致凭据不同步。
向电话号码发送外发消息并非无成本——仅在设置了时长或成功条件的情况下，才将
```
sendblue send
```
接入钩子或循环，避免向收件人发送垃圾信息。
验证码通过邮箱发送；请将注册时使用的邮箱视为账户的恢复手段。

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.

仅支持E.164格式。
```
5551234567
```
或
```
(555) 123-4567
```
会失败——必须使用
```
+15551234567
```
。
免费套餐未验证联系人。向未先发消息的联系人发送外发消息会返回错误——请让联系人先向你的Sendblue号码发送一条短信，然后用
```
sendblue contacts
```
确认。
非交互式模式下的两步设置。仅使用
```
--email
```
只会发送验证码；必须再次调用并传入
```
--code
```
及其他标志才能完成设置。
凭据按用户隔离。
```
~/.sendblue/credentials.json
```
仅对所有者可见（权限
```
600
```
）。不要使用
```
sudo
```
污染root用户主目录——以运行
```
setup
```
的同一用户身份重新运行才能正常工作。

Related Skills

链接

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

README及完整标志参考：https://github.com/sendblue-api/sendblue-cli
Sendblue官网：https://sendblue.com
API文档（更详细的协议说明）：https://docs.sendblue.com

sendblue-cli

Original

Translation

Sendblue CLI

Sendblue CLI

Overview

概述

When to Use This Skill

何时使用该工具

How It Works

使用流程

Step 1: Install

步骤1：安装

or one-shot:

或单次使用：

Step 2: Set up an account

步骤2：设置账户

Step 3: Send messages

步骤3：发送消息

Step 4: Manage contacts and plan

步骤4：管理联系人和套餐

Command Reference

命令参考

Examples

示例

Example 1: Notify when a long task finishes

示例1：长任务完成时通知

Example 2: Read recent inbound for a specific contact

示例2：读取特定联系人的近期入站消息

Example 3: Verify creds are good before a batch send

示例3：批量发送前验证凭据有效性

Example 4: Wire to a Claude Code Stop hook

示例4：接入Claude Code Stop钩子

Best Practices

最佳实践

Limitations

局限性

Security & Safety Notes

安全注意事项

Common Pitfalls

常见陷阱

Related Skills

相关工具

Links

链接

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

示例4：接入Claude Code
`Stop`
钩子