命令行工具

gregor 命令可以从 Shell 脚本、定时任务和 CI 发送提醒。它是一个没有依赖的单文件程序，支持 Linux、macOS 和 Windows。它替你完成原本要围绕 curl 自己写的部分：

它按原样发送你给的内容。所有限制都由服务器检查，超过时命令会输出服务器返回的错误。

这个命令只能发送：不能读取收件箱，也不能修改频道。发布后，下载链接会出现在首页。把文件放到 PATH 中即可。

配置

命令从环境变量读取链接和密钥，这样它们不会出现在 Shell 历史和进程列表中：

变量	用途
`SEND_URL`	频道的发送链接。可以用 `-url` 覆盖。
`CHANNEL_KEY`	频道密钥，格式为 `ck1:…`。设置后，每条提醒都会加密。也可以用 `-key-file` 指定保存密钥的文件。
`HEARTBEAT_URL`	`gregor heartbeat` 使用的心跳链接。

export SEND_URL='https://<api-host>/v1/send/<token>'

gregor send "构建失败" "main 分支有 3 个测试失败"

第一个参数是标题，第二个参数是可选的正文。正文写 - 时从标准输入读取：

df -h | gregor send -level high "磁盘快满了" -

参数	请求字段
`-level`	`level`：`urgent`、`high`、`normal`（默认）或 `silent`
`-link`	`url`
`-event`、`-subject`、`-fingerprint`	`event.type`、`event.subject`、`event.fingerprint`；见重复事件
`-thread`	`thread_key`
`-ack`	`require_ack`
`-receipt`	`receipt`
`-payload`	`payload`，一个 JSON 对象；加密时不可用
`-idempotency-key`	`idempotency_key`；不填时自动生成

命令会输出提醒 ID，有回执时同时输出回执 ID。加 -json 输出完整响应，加 -q 则不输出任何内容。

把从应用复制的密钥设为 CHANNEL_KEY，然后照常发送：

export CHANNEL_KEY='ck1:<channel_id>:<key_version>:<key>'
gregor send -event backup.failed -subject host:nas "备份失败" "nas：退出码 2"

标题、正文和链接在你的机器上加密。级别、事件和线程仍然对服务器可见，不要在其中放机密内容。设置了密钥时 -payload 会被拒绝，因为负载会以明文发送。轮换密钥后，记得更新 CHANNEL_KEY。

gregor run 运行一条命令，原样输出它的内容，并以它的退出码退出。命令失败时，发送一条提醒：

gregor run -- /usr/local/bin/backup.sh --full

命令写在 -- 之后。提醒的默认内容：

字段	默认值
标题	`backup.sh failed on <主机名>`；可用 `-title` 修改
正文	退出码、运行时长和最后 20 行输出，最多 800 个字符；行数可用 `-lines` 修改
级别	`high`
事件	类型 `command.failed`，主体 `host:<主机名>:<命令>`，重复失败会更新同一条提醒

send 的所有参数都可以用于 run。命令无法启动时，也会发送提醒，并以退出码 127 退出。

要发现根本没有运行的任务，可以在命令成功后上报心跳：

30 2 * * * gregor run -heartbeat "$HEARTBEAT_URL" -- /usr/local/bin/backup.sh

gregor heartbeat

使用 HEARTBEAT_URL，或作为参数传入的链接。加密频道不支持心跳。

网络错误、服务器错误和 429 响应最多重试 3 次；用 -retries 设置次数，用 -timeout 设置每次请求的超时（默认 10s）。遇到 429 时按 Retry-After 等待，最长一分钟。每次重试都使用同一个幂等键，所以提醒不会被创建两次。

其他错误不会重试。命令会输出错误码和处理方法，并以退出码 1 退出。错误信息只包含主机名，不会包含链接中的令牌。