ntfy 2.32.0 常用 CLI 命令与工具详解

目标：系统梳理 ntfy 2.32.0 命令行工具（ntfy CLI）的全部常用命令——发布、订阅、用户/令牌/授权管理、服务端运行与密钥工具，每个子命令给出实测命令与真实回显、真实默认值与易错点。ntfy CLI 的特点是「一个二进制双角色」：客户端命令（publish/subscribe）不需要本地服务端即可对任意 ntfy 服务器收发，服务端命令（serve/user/token/access/tier/webpush）直接操作本机服务。全部实测在 Ubuntu 22.04.5 LTS + ntfy 2.32.0 完成，安装与配置见本专栏《Ubuntu 22.04 安装 ntfy 2.32.0 指南》与《ntfy 2.32.0 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS，x86_64/amd64；
ntfy 版本：2.32.0（二进制 /usr/local/bin/ntfy，ntfy version 2.32.0）；
实测时间：2026-10-21；
服务端：本机 systemd 托管，HTTP 监听 127.0.0.1:8144（下文 URL 均写 http://127.0.0.1:8144）；已启用认证 auth-default-access: deny-all；
实测账号：用户 phil（密码 q1w2e3r4，演示用途），访问令牌 tk_ffgc4viepv02qt8eo6q5eonpcshn6（本次实测中 ntfy token add 的真实产物）；
客户端配置：/root/.config/ntfy/client.yml（root 用户家目录形态，实测使用）。

二、工具概览

ntfy CLI 的命令全景（ntfy --help 实测）：

ntfy --help

实测输出（节选）：

NAME:
   ntfy - Simple pub-sub notification service

USAGE:
   ntfy [OPTION..]

VERSION:
   2.32.0

COMMANDS:
   help, h  Shows a list of commands or help for one command
   Client commands:
     publish, pub, send, trigger  Send message via a ntfy server
     subscribe, sub               Subscribe to one or more topics on a ntfy server
   Server commands:
     access   Grant/revoke access to a topic, or show access
     serve    Run the ntfy server
     tier     Manage/show tiers
     token    Create, list or delete user tokens
     user     Manage/show users
     webpush  Generate keys, in the future manage web push subscriptions

GLOBAL OPTIONS:
   --debug, -d          enable debug logging (default: false) [$NTFY_DEBUG]
   --trace              enable tracing (very verbose, be careful) (default: false) [$NTFY_TRACE]
   --no-log-dates, --no_log_dates    disable the date/time prefix (default: false) [$NTFY_NO_LOG_DATES]
   --log-level value, --log_level value    set log level (default: "INFO") [$NTFY_LOG_LEVEL]
   --log-format value, --log_format value  set log format (default: "text") [$NTFY_LOG_FORMAT]
   --help, -h           show help
   --version, -v        print the version

Try 'ntfy COMMAND --help' or https://ntfy.sh/docs/ for more information.

命令分两类：

类别	命令	作用	需要本地服务端
客户端	`publish`（别名 pub/send/trigger）	发布消息	否（对任意 ntfy 服务器）
客户端	`subscribe`（别名 sub）	订阅主题（打印/执行命令/常驻服务）	否
服务端	`serve`	运行 ntfy 服务	是
服务端	`user` / `token` / `access`	用户、令牌、主题授权管理	是（直读 auth-file）
服务端	`tier` / `webpush`	配额层级 / Web Push 密钥工具	是

💡 说明：publish 与 subscribe 的所有选项都有 $NTFY_* 环境变量等价形态（如 --title ↔ $NTFY_TITLE），脚本集成时可任选。ntfy --version 完整输出（实测）：ntfy 2.32.0 (9d0b6d9), runtime go1.27.1, built at 2026-10-18T12:40:17Z。

三、前置条件

CLI 已安装（同服务端一起，见安装指南）；仅做客户端时无需启动服务端；
面向自建服务器且已开启认证时，先备好凭据（用户名密码或 tk_ 令牌）：令牌由 ntfy token add 签发（见 4.4 节）；
客户端默认配置文件：root 用户读 /etc/ntfy/client.yml，普通用户读 ~/.config/ntfy/client.yml（--help 原文：「The default config file for all client commands is /etc/ntfy/client.yml (if root user), or ~/.config/ntfy/client.yml for all other users」）——「默认服务器/默认凭据/常驻订阅」都定义在这里。本文为 root 环境创建家目录形态并用 --config 显式指向（避免歧义）。

四、各工具详解

4.1 ntfy publish（发布消息）

基本形态：ntfy publish [OPTIONS..] TOPIC [MESSAGE...]。TOPIC 支持三种写法——短主题（走 client.yml 的 default-host）、host/topic 形式、完整 URL。自建服务器实测（URL 形式 + 令牌）：

ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic 'msg via CLI url form'

{"id":"qGCtfQQlcTtf","time":1792589155,"expires":1792632355,"event":"message","topic":"phil-topic","message":"msg via CLI url form"}

标题 + 优先级 + 标签（-t 标题、-p 优先级 1-5、--tags 逗号分隔标签/emoji 短码）：

ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 -t 'Backup report' -p high --tags warning,rotating_light http://127.0.0.1:8144/phil-topic 'Disk usage 92% on /var'

{"id":"k4cW9Lbtx5bC","time":1792589155,"expires":1792632355,"event":"message","topic":"phil-topic","title":"Backup report","message":"Disk usage 92% on /var","priority":4,"tags":["warning","rotating_light"]}

priority 的取值映射（--help 原文）：1=min、2=low、3=default、4=high、5=max；high 是 4 的别名。

定时延迟发布（--delay 支持相对时长与绝对时刻如 8:30am）：

ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 --delay=30s http://127.0.0.1:8144/phil-topic 'delayed message via CLI'

{"id":"Iv6C1oSakrUq","time":1792589185,"expires":1792632385,"event":"message","topic":"phil-topic","message":"delayed message via CLI"}

注意回显中 time 比上一条晚 30 秒——服务端按调度时间入缓存。

附件上传（--file，需服务端启用 attachment-cache-dir）：

echo 'test attachment content 2026-10-21' > /tmp/report.txt
ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 --file=/tmp/report.txt http://127.0.0.1:8144/phil-topic 'report attached'

{"id":"NazLJG4n7l7Q","time":1792589171,"expires":1792632371,"event":"message","topic":"phil-topic","message":"report attached","attachment":{"name":"report.txt","type":"text/plain; charset=utf-8","size":35,"expires":1792599971,"url":"http://127.0.0.1:8144/file/NazLJG4n7l7Q.txt"}}

从 stdin 读正文：

echo 'message from stdin' | ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic

{"id":"FtLKKwCnIify","time":1792590860,"expires":1792634060,"event":"message","topic":"phil-topic","message":"message from stdin"}

环境变量形态（配合 client.yml 的 default-host + default-token，TOPIC 由 NTFY_TOPIC 提供）：

NTFY_TOPIC=phil-topic ntfy publish 'sent via NTFY_TOPIC env'

{"id":"IAfnc9TKvlm2","time":1792590411,"expires":1792633611,"event":"message","topic":"phil-topic","message":"sent via NTFY_TOPIC env"}

对应 client.yml（实测文件内容）：

default-host: http://127.0.0.1:8144
default-token: tk_ffgc4viepv02qt8eo6q5eonpcshn6

无正文触发（ntfy trigger 是 publish 的别名，正文固定为 "triggered"，适合 Webhook 场景）：

ntfy trigger --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic

{"id":"vwo3oxS4RjJB","time":1792590424,"expires":1792633626,"event":"message","topic":"phil-topic","message":"triggered"}

命令完成后发布（--wait-cmd：执行给定命令，结束后自动把结果发出来，消息体自带执行耗时）：

ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 --wait-cmd http://127.0.0.1:8144/phil-topic sh -c 'sleep 2; echo job done'

{"id":"v966or7OWf9o","time":1792590426,"expires":1792633626,"event":"message","topic":"phil-topic","message":"Command succeeded after 2.002s: sh -c \"sleep 2; echo job done\""}

同族选项 --wait-pid <PID>：等待指定进程退出后发布（监控长任务利器）。

publish 常用选项速查（默认值取自实测 ntfy publish --help）：

选项	说明
`-t, --title`	消息标题（$NTFY_TITLE）
`-p, --priority`	1-5（min/low/default/high/max）
`-T, --tags`	逗号分隔标签与 emoji 短码
`-D, --delay/--at/--in`	定时发布
`-U, --click`	通知点击跳转 URL
`-i, --icon`	通知图标 URL
`-A, --actions`	通知按钮（JSON 或简单定义）
`-f, --file`	上传附件；`--file=-` 从 stdin 读
`-e, --email`	同时转发邮件（服务端需配 smtp-sender）
`-S, --sequence-id`	序列 ID，更新同 ID 的既有通知
`-u, --user`	用户名[:密码] 认证
`-k, --token`	访问令牌认证
`--wait-pid` / `--wait-cmd`	等进程退出 / 等命令完成后发布
`--no-cache`	不在服务端缓存（默认 false）
`--no-firebase`	不转发 FCM（默认 false）
`-q, --quiet`	不打印回显 JSON

三种模式（--help 原文列举）。

模式一：流式打印（长驻，逐条打印 JSON）：

timeout 8 ntfy subscribe --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic

（订阅期间另开会话发布两条，实测收到的输出：）

{"id":"C8JEHsHvEmqg","time":1792589241,"expires":1792632441,"event":"message","topic":"phil-topic","message":"stream msg 1"}
{"id":"JvNinJmbuW0J","time":1792589241,"expires":1792632441,"event":"message","topic":"phil-topic","message":"stream msg 2"}

模式二：一次性拉取退出（--poll，可配 --since）：

ntfy subscribe --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 --poll http://127.0.0.1:8144/phil-topic | head -3

{"id":"RnmYyIKH1UlF","time":1792590638,"expires":1792633838,"event":"message","topic":"phil-topic","message":"hello from-config"}
{"id":"qpxTv3oDSAGd","time":1792590663,"expires":1792633863,"event":"message","topic":"phil-topic","message":"hello from-config 2"}
{"id":"bABuFGYgwMBY","time":1792590682,"expires":1792633882,"event":"message","topic":"phil-topic","message":"hello from-config 3"}

模式三：命令执行（ntfy subscribe TOPIC COMMAND，消息字段以 $NTFY_*/$message 等环境变量传入命令）：

timeout 8 ntfy subscribe --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic 'sh -c "echo got: $message"'

（订阅期间发布一条 mode two cmd test，订阅端命令被触发的实测输出：）

got: mode two cmd test

字段变量全家福（--help 原文）：$id/$time/$topic/$message（简写 $m）/$title（$t）/$priority（$prio）/$tags/$raw。

服务模式：--from-config（systemd 用户级单元 ntfy-client.service 的运行方式；读取 client.yml 的 subscribe: 块，每条订阅可带 command/if 条件过滤）。实测 client.yml：

default-host: http://127.0.0.1:8144
default-token: tk_ffgc4viepv02qt8eo6q5eonpcshn6

subscribe:
  - topic: phil-topic
    command: 'echo got: $message'

运行与验证（发布一条，订阅端命令被触发执行）：

ntfy subscribe --config=/root/.config/ntfy/client.yml --from-config &
sleep 3
ntfy publish --token tk_ffgc4viepv02qt8eo6q5eonpcshn6 http://127.0.0.1:8144/phil-topic 'hello from-config 3'

订阅端实测输出（$message 展开成功）：

got: hello from-config 3

⚠️ 注意：① root 默认读 /etc/ntfy/client.yml——你的 subscribe 块写在家目录配置时必须显式 --config= 指向，否则报「must specify topic」（实测踩过）；② command: 的值含冒号空格时 YAML 必须加引号，否则解析报 mapping values are not allowed in this context（实测踩过）；③ 正式常驻用 deb 包自带的用户级单元：systemctl --user enable ntfy-client.service。

4.3 ntfy user（用户管理，服务端命令）

直接读写 server.yml 中 auth-file 指向的用户库（无需 --config，默认读 /etc/ntfy/server.yml；auth-file 未配置时执行会提示 auth unconfigured）。

创建用户（交互输两次密码）：

ntfy user add phil

user phil added with role user

脚本场景用环境变量免交互（--help 原文）：NTFY_PASSWORD=... ntfy user add phil；管理员角色加 --role=admin。

列出用户与 ACL：

ntfy user list

user phil (role: user, tier: none)
- read-write access to topic phil-topic
user * (role: anonymous, tier: none)
- no topic-specific permissions
- no access to any (other) topics (server config)

生成密码哈希（供 auth-users 声明式配置用，bcrypt）：

ntfy user hash

（交互输入两次密码 q1w2e3r4，实测输出：）

$2a$10$iKFDQw2dxAhw3UeGfR7dsOQVszARiVNawWJMswzClZH2joOo/t73a

删除用户：

ntfy user del phil2

user phil2 removed

（删除不存在的用户实测回显：user phil2 does not exist。）

4.4 ntfy token（访问令牌管理，服务端命令）

签发（tk_ 前缀，仅创建时展示一次；--expires/--duration 可设过期，默认永久）：

ntfy token add phil

token tk_ffgc4viepv02qt8eo6q5eonpcshn6 created for user phil, never expires

列出：

ntfy token list

user phil
- tk_ffgc4viepv02qt8eo6q5eonpcshn6, never expires, accessed from 127.0.0.1 at 21 Oct 26 13:51 UTC

删除（注意：需要「用户名 + 令牌」两个参数，只传令牌会报错）：

ntfy token remove phil tk_ne1dhazal11kx7y7vqlmiizl1c6pa

token tk_ne1dhazal11kx7y7vqlmiizl1c6pa for user phil removed

（错误用法实测：ntfy token remove tk_ne1d... → username and token expected, type 'ntfy token remove --help' for help。）

4.5 ntfy access（主题授权管理，服务端命令）

授权（rw/read-only/write-only/none；主题支持 phil-* 通配）：

ntfy access phil phil-topic rw

granted read-write access to topic phil-topic

回收：

ntfy access phil phil-topic none

revoked all access to topic phil-topic

user phil (role: user, tier: none)
- no access to topic phil-topic

查看全部 ACL（无参调用）：

ntfy access

user phil (role: user, tier: none)
- read-write access to topic phil-topic
user * (role: anonymous, tier: none)
- no topic-specific permissions
- no access to any (other) topics (server config)

4.6 ntfy serve（服务端运行）

ntfy serve 以配置文件运行服务端，命令行参数可逐项覆盖配置文件（完整参数与默认值见《ntfy 2.32.0 配置参数详解》3.2 节，此处给最小实测）。生产由 systemd 托管（单元 ExecStart=/usr/local/bin/ntfy serve --no-log-dates）；手动前台运行常用于排障：

timeout 6 ntfy serve --listen-http :8145 --cache-file /tmp/tc.db --no-log-dates

实测输出（另开会话 ss -ltn | grep 8145 见 LISTEN）：

INFO Listening on :8145[http], ntfy 2.32.0, log level is INFO (tag=startup)

--no-log-dates 去掉日志时间前缀（journalctl 已带时间戳，避免重复）。

4.7 ntfy tier 与 ntfy webpush（服务端工具）

tier——多租户配额层级管理（增删改查），面向运营类实例；未创建任何 tier 时查询为空（实测）：

ntfy tier list

（无输出，空列表）

webpush keys——生成 Web Push（VAPID）密钥对，输出即配置模板（实测）：

ntfy webpush keys

Web Push keys generated. Add the following lines to your config file:

web-push-public-key: BKuREoWwSk-P9UyJKDt6TBEzTbl0tOiFT2SKLHH4diRXlF_-CZgOv-8xu6wK6cA2BA7jlgU1EtbWENum5QvmZJs
web-push-private-key: N5X-kY4dYgaCFEOwx6kE23adw7fN8jxKdwFmgFPTG58
web-push-file: /var/cache/ntfy/webpush.db # or similar
web-push-email-address: <email address>

See https://ntfy.sh/docs/config/#web-push for details.

⚠️ 注意：每次执行 webpush keys 都生成新密钥，生成后把三行配置写入 server.yml 并重启；已配好的实例重跑会产出与线上不一致的新密钥（浏览器订阅需重新登记），不要重复执行。

五、注意事项

默认服务器是公共服务 ntfy.sh：短主题形式（ntfy publish mytopic ...）发往 client.yml 的 default-host，未配置时即 https://ntfy.sh。带自建令牌发往公共服务会收到 40101 unauthorized（实测踩过）——自建场景要么写完整 URL，要么在 client.yml 配 default-host；
无协议头的 host:port 默认按 https：ntfy publish 127.0.0.1:8144/phil-topic 实测报 Post "https://127.0.0.1:8144/phil-topic": http: server gave HTTP response to HTTPS client——HTTP 自建环境必须写全 http://；
选项必须放在位置参数之前：publish 的 MESSAGE 是可变位置参数，--trigger/--wait-cmd 写在 TOPIC 之后会被当作消息文本（实测 --trigger 变成消息体）；统一「先选项后主题」；
ntfy token remove 需要用户名+令牌两个参数，单参数报 username and token expected；
服务端命令（user/token/access/tier/webpush）直读 /etc/ntfy/server.yml：auth-file 未配置时执行 user/token/access 会提示 auth unconfigured；非默认路径部署时把全局 --config 放在子命令之前（实测 ntfy user add --config=... phil 报 flag provided but not defined: -config）；
令牌仅创建时展示一次，创建即复制保存；泄露后 ntfy token remove <user> <token> 即时吊销。

六、常见问题（FAQ）

Q1：ntfy publish 返回 40101？ 认证失败。检查：目标服务器是否是你以为的那台（短主题会发往 ntfy.sh，见注意事项 1）；令牌是否完整（tk_ 开头整串）；令牌是否已被删除（ntfy token list 核对）。

Q2：--wait-cmd 报 exec: "--": executable file not found？ --wait-cmd 与命令之间不需要 -- 分隔符，直接写命令：ntfy publish --wait-cmd <topic> sh -c '...'（实测报错后去掉 -- 恢复正常）。

Q3：ntfy user add --config=/etc/ntfy/server.yml phil 报 flag provided but not defined: -config？ --config 是全局选项，必须放在子命令之前：ntfy --config=/etc/ntfy/server.yml user add phil；且服务端命令默认就读 /etc/ntfy/server.yml，通常无需显式传。

Q4：ntfy subscribe --from-config 报 must specify topic？ 默认配置文件里没有 subscribe: 块（root 读 /etc/ntfy/client.yml）。用 --config= 显式指向含 subscribe 块的文件，或把订阅块写进默认配置。

Q5：脚本里怎么免交互创建用户？ NTFY_PASSWORD=q1w2e3r4 ntfy user add phil（--help 原文口径）；更推荐先 ntfy user hash 生成 bcrypt 哈希写入 auth-users 声明式配置。

Q6：CLI 能否不装服务端单独用？ 能。ntfy 单二进制即是完整 CLI，复制到任何机器（或 Windows/macOS 官方包）即可 publish/subscribe 对任意 ntfy 服务器收发；apt/deb 安装的用户级订阅常驻用 ntfy-client.service。

七、参考链接

官方 CLI 发布文档：https://docs.ntfy.sh/docs/publish/cli/
官方 CLI 订阅文档：https://docs.ntfy.sh/docs/subscribe/cli/
各子命令帮助（最准的参数与默认值）：ntfy <COMMAND> --help
client.yml 说明（订阅服务模式）：https://docs.ntfy.sh/docs/config/#clientyml
本专栏相关篇目：《ntfy 2.32.0 介绍与选型指南》、《Ubuntu 22.04 安装 ntfy 2.32.0 指南》、《ntfy 2.32.0 配置参数详解》

ntfy 2.32.0 常用 CLI 命令与工具详解

ntfy 2.32.0 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、各工具详解

4.1 ntfy publish（发布消息）

4.2 ntfy subscribe（订阅消息）

4.3 ntfy user（用户管理，服务端命令）

4.4 ntfy token（访问令牌管理，服务端命令）

4.5 ntfy access（主题授权管理，服务端命令）

4.6 ntfy serve（服务端运行）

4.7 ntfy tier 与 ntfy webpush（服务端工具）

五、注意事项

六、常见问题（FAQ）

七、参考链接