gotify

Gotify CLI 客户端

通过 REST API v2.0.2，在可自托管的 Gotify 服务上发送和管理推送通知。

执行规则

直接运行用户请求的命令，不要事先检查依赖项、环境变量或配置。如果出现问题，脚本会报出明确错误；届时再检查并修复。

环境变量

变量	必需	用途
GOTIFY_URL	✅	服务基础 URL，例如 https://gotify.example.com
GOTIFY_CLIENT_TOKEN	✅	客户端令牌 — 管理应用和客户端、读取消息
GOTIFY_APP_TOKEN	✅	应用令牌 — 发送消息

脚本会自动从 ~/.wmyskills/.env（供所有技能共用）读取这些变量；如果脚本目录中存在 scripts/.env，则优先使用其中的配置。请以 scripts/.env.example 为模板，将变量添加到 ~/.wmyskills/.env，切勿覆盖现有文件。令牌缺失时会显示明确错误；也可以通过 --token 在每次调用时传入令牌。

要求

# Core — stdlib only (no install needed)
# WebSocket (optional, for ws-subscribe only):
pip install websocket-client

用法

脚本：scripts/gotify_client.py

python scripts/gotify_client.py <command> [options]

🔔 发送通知

python scripts/gotify_client.py send \
  --message "Deployment succeeded" \
  --title "CI/CD Alert" \
  --priority 5

标志	必需	描述
--message / -m	✅	消息正文（支持 Markdown）
--title / -t		通知标题
--priority / -p		0–10（0=静默，10=紧急；省略时不发送，API 使用 0）
--extras		插件专用数据的 JSON 字符串
--token		覆盖应用令牌

Extras 示例（Firebase 推送配置）：

python scripts/gotify_client.py send -m "Hello" --extras '{"firebase":{"priority":"high"}}'

📱 应用（消息来源）

# List all applications
python scripts/gotify_client.py list-apps

# Create a new application
python scripts/gotify_client.py create-app \
  --name "Backup Bot" \
  --description "Backup notifications" \
  --default-priority 3

# Delete an application
python scripts/gotify_client.py delete-app --id 5

create-app 标志	必需	描述
--name	✅	应用名称
--description / -d		描述
--default-priority		默认消息优先级（0–10）
--image		应用图片 URL
--internal		标记为内部应用（标志，无需传值）

create-app 返回的 token 是用于发送消息的应用令牌。请妥善保管。

📲 客户端（接收设备）

# List all clients
python scripts/gotify_client.py list-clients

# Create a new client
python scripts/gotify_client.py create-client --name "iPhone"

# Delete a client
python scripts/gotify_client.py delete-client --id 3

📬 消息

# List recent messages (default: 30)
python scripts/gotify_client.py list-messages --limit 50

# Pagination — get messages after ID 100
python scripts/gotify_client.py list-messages --since 100

# Use a specific token to list messages (app or client token)
python scripts/gotify_client.py list-messages --token <token>

# Delete a single message
python scripts/gotify_client.py delete-message --id 42

# Bulk delete: all messages with ID < 500
python scripts/gotify_client.py delete-messages --before 500

# Bulk delete from a specific app
python scripts/gotify_client.py delete-messages --app-id 3 --before 500

list-messages 标志	描述
--limit	返回的最大消息数（1–200；默认值为 30）
--since	消息 ID 偏移量 — 返回 ID 大于此值的消息
--token	覆盖令牌（默认使用环境变量中的客户端令牌）

🔌 插件

# List installed plugins
python scripts/gotify_client.py list-plugins

# Enable a plugin
python scripts/gotify_client.py toggle-plugin --id 1

# Disable a plugin
python scripts/gotify_client.py toggle-plugin --id 1 --disable

❤️ 服务健康状态与版本

# Health check
python scripts/gotify_client.py health

# Version info
python scripts/gotify_client.py version

📡 实时 WebSocket 流

订阅实时消息（需要 websocket-client）：

pip install websocket-client
python scripts/gotify_client.py ws-subscribe
# Override token:
python scripts/gotify_client.py ws-subscribe --token <client-or-app-token>

每条收到的消息都会以一个 JSON 对象的形式输出。

API 密钥概念

• 应用令牌（GOTIFY_APP_TOKEN）：用于通过 /message 发送消息
• 客户端令牌（GOTIFY_CLIENT_TOKEN）：用于在其他所有场景中管理应用、客户端和消息
• 令牌通过 X-Gotify-Key 请求头传递（脚本会自动处理）

故障排除

错误	原因	修复方法
GOTIFY_URL not set	缺少环境变量	设置 GOTIFY_URL=https://your-server
401 Unauthorized	令牌错误或缺失	检查所需的令牌类型；确认环境变量
403 Forbidden	发送消息时使用了客户端令牌	使用应用令牌调用 /message
Connection refused	服务已关闭	运行 health 进行验证
No app token	未配置令牌	设置 GOTIFY_APP_TOKEN 或使用 --token