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

> Pocket Alert CLI 已重写并开源。支持优先级、操作按钮、图片和定时发送，用 exec 包装任意命令，用 watch 把日志行变成推送通知，并在全屏终端界面中浏览所有内容。

*17.10.2026*

<!-- source: https://pocketalert.app/zh/blog/pocketalert-cli-2 -->

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

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

![终端中的 Pocket Alert CLI 收件箱](https://cdn.pocketalert.app/blog/pocketalert-cli-2-inbox.jpg)

## 安装

**macOS 和 Linux：**

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

**Homebrew：**

```bash
brew install pocketalert/tap/pocketalert
```

**Go：**

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

**Windows：**从最新版本中下载 [pocketalert_windows_amd64.zip](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_windows_amd64.zip)，并将 `pocketalert.exe` 放入 PATH。每个版本都提供 macOS 和 Linux（Intel 与 ARM）以及 Windows（x64）的压缩包，并附带校验和。

然后使用 [API 密钥](/account/apikeys) 登录一次：

```bash
pocketalert auth
```

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

## 发送，支持 API 的全部功能

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

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

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

```bash
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 响应。

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

```bash
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` 会运行命令，照常输出其内容，并在命令结束时发送推送：

```bash
pocketalert exec -- ./backup.sh
```

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

```bash
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` 从管道中读取行，并将其作为通知发送：

```bash
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` 全部标记已读。应用打开期间，新消息会自动出现。

![终端预览窗格中带操作按钮的消息](https://cdn.pocketalert.app/blog/pocketalert-cli-2-actions.jpg)

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

![在终端中编辑新消息](https://cdn.pocketalert.app/blog/pocketalert-cli-2-compose.jpg)

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

![终端界面中的应用列表](https://cdn.pocketalert.app/blog/pocketalert-cli-2-applications.jpg)

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

## 从脚本管理账户

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

```bash
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](/blog/claude-code-push-notifications)、[Codex](/blog/codex-notifications) 以及 [Cline 和 Aider](/blog/cline-aider-notifications) 指南中的 Hook 脚本可以用 `pocketalert send` 替代 curl。对于 cron 和 CI，`exec` 可以替代大多数 `|| curl` 单行命令。

[安装 CLI](/tools/cli)，运行 `pocketalert auth`，然后试试 `pocketalert ui`。
