返回博客

Pocket Alert CLI 2.1:优先级、exec、watch 与终端里的收件箱

Pocket Alert CLI 2.1:优先级、exec、watch 与终端里的收件箱

最早的 Pocket Alert CLI 只能发送标题和消息。这足以证明想法可行,但也仅此而已:没有优先级、没有操作按钮、没有定时发送,也无法应对最常见的需求,即在长时间运行的命令结束时通知你。

2.0 版是一次重写。它位于独立仓库中,采用 MIT 许可证,一条命令即可安装,并覆盖 API 的全部功能。2.1 版今日发布,新增 pocketalert ui:一个全屏终端应用,用于查看收件箱、定时消息、应用、设备和 Webhook。

终端中的 Pocket Alert CLI 收件箱

安装

macOS 和 Linux:

curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh

Homebrew:

brew install pocketalert/tap/pocketalert

Go:

go install github.com/PocketAlert/cli/cmd/pocketalert@latest

**Windows:**从最新版本中下载 pocketalert_windows_amd64.zip,并将 pocketalert.exe 放入 PATH。每个版本都提供 macOS 和 Linux(Intel 与 ARM)以及 Windows(x64)的压缩包,并附带校验和。

然后使用 API 密钥 登录一次:

pocketalert auth

密钥在隐藏输入的提示中输入,经 API 校验后保存到 ~/.pocketalert/config.json,权限为 600。在 CI 中,请改为设置 POCKETALERT_API_KEY,它的优先级高于已保存的密钥。

发送,支持 API 的全部功能

基本用法现在只需两个参数:

pocketalert send "Deploy finished" "v1.4.2 is live"

消息内容可以来自标准输入,因此命令输出可以直接发到你的手机:

df -h | pocketalert send "Disk report"

其他选项都通过参数设置:

  • 优先级。 -l silent|low|default|high|critical,或使用 -2 到 2。付费套餐中,critical 可以突破勿扰模式;免费套餐则会以 high 发送。
  • 定时发送。 --at "2026-10-20 09:50" 按账户所在时区设置,或使用 --in 1d12h。付费套餐最多可提前 30 天。pocketalert scheduled list 和 scheduled cancel <tid> 用于管理排队中的消息。
  • 操作按钮。 最多三个 --action type:label:value,其中类型可以是 view、http 或 copy。付费套餐可用。
  • 图片。 --image ./screenshot.png 或 https:// 链接。付费套餐可用。
  • 发送目标。 -a 指定应用,-d 指定单个设备。
  • 脚本化。 -q 仅输出消息 ID,所有命令都支持 --json,以返回原始 API 响应。

一个部署失败的完整示例:

pocketalert send "Deploy failed" "main@4f2c" -l critical \
  --action "view:Open logs:https://ci.example.com/run/1" \
  --action "http:Retry:https://ci.example.com/run/1/retry" \
  --action "copy:Copy SHA:4f2c9e1"

http 按钮默认发送 POST 请求。如需其他方法,可以写成 http:Ack:GET https://…,或传入包含请求头和请求体的完整 JSON 格式。

exec:命令结束时推送

很多人过去会为此编写包装脚本,现在已内置在 CLI 中。exec 会运行命令,照常输出其内容,并在命令结束时发送推送:

pocketalert exec -- ./backup.sh

推送标题为命令内容,成功时带 ✓,失败时带 ✗ 和退出码。消息正文包含运行时长、主机名以及输出的最后十行。除非你另行设置优先级,失败通知会以 high 发送。命令的退出码会原样传递,因此 exec 可以安全地用于脚本、cron 和 CI。

pocketalert exec --on failure -l critical -- terraform apply -auto-approve
pocketalert exec -t "Nightly import" --tail 20 -- python import.py

--on 用于选择何时通知:always、success 或 failure。--tail 用于设置包含的输出行数,设为 0 则不包含输出。

watch:把日志行变成推送

watch 从管道中读取行,并将其作为通知发送:

tail -f app.log | grep --line-buffered ERROR | pocketalert watch -t "app errors"
journalctl -fu nginx | pocketalert watch --batch 1m -l high

在批处理窗口内(默认为五秒)到达的日志行会合并为一条推送,标题中会显示行数。一次突发的两百条错误只消耗每日额度中的一条消息,而不是两百条。

pocketalert ui

运行 pocketalert ui,终端即变成 Pocket Alert 客户端。共有五个标签页,可用 tab 或 1 到 5 切换:收件箱、定时、应用、设备和 Webhook。

收件箱列出消息及其优先级、应用和时间,未读消息以圆点标记。右侧面板完整显示选中的消息,包括其操作按钮及目标。按 / 搜索,按 u 仅显示未读,按 r 标记单条已读,按 a 全部标记已读。应用打开期间,新消息会自动出现。

终端预览窗格中带操作按钮的消息

按 n 打开编辑器:依次填写标题和消息,然后选择应用、设备、优先级、发送时间、图片,以及最多三个操作按钮,格式与 type:label:value 参数中的 send 相同。按 ctrl+s 发送。在已有消息上按 f,可再次在编辑器中打开,用于重新发送或作为模板使用。

在终端中编辑新消息

其他标签页用于管理账户的其余内容。应用列出每个应用及其默认优先级;无需离开键盘即可创建、重命名、修改优先级或删除,按 enter 可查看该应用的消息。设备列出你的手机,可重命名或移除。Webhook 列出你的 Webhook 及其请求历史,按 y 可复制 Webhook 链接。定时显示排队中的消息,按 d 取消。

终端界面中的应用列表

所有破坏性操作都会先请求确认,按 ? 可查看全部快捷键。

从脚本管理账户

API 的其余功能同样覆盖,且每个命令都支持 --json:

pocketalert usage                                   # today's quota
pocketalert messages list -n 20
pocketalert messages read --all
pocketalert apps create -n "Production" -c "#EF4444" -l high
pocketalert webhooks create -n Grafana -m "%title%: %message%" -l high
pocketalert webhooks history <tid> --status error
pocketalert devices rename <tid> "Work phone"

现在,你还可以通过 CLI 为应用和 Webhook 设置默认优先级,并为 Webhook 设置操作按钮,其中可使用 %field.path% 占位符,从负载中取值填充。例如,Grafana 告警可以以 high 优先级到达,并附带一个直接打开对应面板的按钮。

运行 pocketalert completion 即可为 zsh、bash 和 fish 启用命令补全。

从 1.x 升级

使用上述任一方式安装 2.1 即可;它会替换旧的二进制文件,并保留你已保存的密钥。以下三项变更可能会影响现有脚本:

  • 现在必须提供消息。 执行 pocketalert send -t "Cron OK" 且不带 -m 会返回错误。请添加消息、通过管道传入,或使用 exec,它会自动生成消息。
  • 不要混用两种格式。 请使用 send "Title" "Message" 或 send -t "Title" -m "Message" 之一。send -t "Title" "Message" 会将第二个参数视为标题并停止处理。
  • 生成的文本请优先使用 -m。 以短横线开头的位置参数消息(例如 AI 代理生成的 Markdown 列表)会被当作选项解析。-m "$text" 始终安全。

如果你在部署脚本中下载发布包,压缩包现在命名为 pocketalert_<os>_<arch>.tar.gz,Windows 上为 .zip。

升级过程中还修复了 1.x 的若干缺陷:webhooks create 现在会遵循 --application 和 --device,Webhook 链接指向正确的主机,错误信息输出到 stderr 而非 stdout,非拉丁字母的标题不再在字符中间被截断,达到每日上限时会显示用量和重置时间,而不是仅返回 429。

适用场景

CLI 现在是从终端通往手机最短的路径,本博客中的指南在能减少代码行数的地方都会使用它。对于编程代理,Claude Code、Codex 以及 Cline 和 Aider 指南中的 Hook 脚本可以用 pocketalert send 替代 curl。对于 cron 和 CI,exec 可以替代大多数 || curl 单行命令。

安装 CLI,运行 pocketalert auth,然后试试 pocketalert ui。

分享这篇文章