wmy2981 Gotify CLI Client
Send and manage push notifications on a self-hosted Gotify server via its REST API v2.0.2.
Execution Rule
Run the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.
Environment Variables
| Variable | Required | Purpose |
|---|---|---|
GOTIFY_URL |
✅ | Server base URL, e.g. https://gotify.example.com |
GOTIFY_CLIENT_TOKEN |
✅ | Client token — manage apps, clients, read messages |
GOTIFY_APP_TOKEN |
✅ | Application token — send messages |
The script loads these from ~/.wmyskills/.env (shared across skills) automatically; a scripts/.env in the script directory takes priority if present. Use scripts/.env.example as the template — add the variables to ~/.wmyskills/.env, never overwriting an existing file. Missing tokens produce a clear error; tokens can also be passed per-call via --token.
Requirements
# Core — stdlib only (no install needed)
# WebSocket (optional, for ws-subscribe only):
pip install websocket-client
Usage
Script: scripts/gotify_client.py
python scripts/gotify_client.py <command> [options]
🔔 Send a Notification
python scripts/gotify_client.py send \
--message "Deployment succeeded" \
--title "CI/CD Alert" \
--priority 5
| Flag | Required | Description |
|---|---|---|
--message / -m |
✅ | Message body (markdown supported) |
--title / -t |
Notification title | |
--priority / -p |
0–10 (0=silent, 10=urgent; omitted → not sent, API uses 0) | |
--extras |
JSON string for plugin-specific data | |
--token |
Override app token |
Extras example (Firebase push config):
python scripts/gotify_client.py send -m "Hello" --extras '{"firebase":{"priority":"high"}}'
📱 Applications (Message Sources)
# 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 Flag |
Required | Description |
|---|---|---|
--name |
✅ | Application name |
--description / -d |
Description | |
--default-priority |
Default message priority (0–10) | |
--image |
Application image URL | |
--internal |
Mark as internal (flag, no value needed) |
The returned
tokenfromcreate-appis the app token for sending messages. Store it securely.
📲 Clients (Receiving Devices)
# 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
📬 Messages
# 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 Flag |
Description |
|---|---|
--limit |
Max messages to return (1–200; default 30) |
--since |
Message ID offset — returns messages with ID > this value |
--token |
Override token (defaults to client token from env) |
🔌 Plugins
# 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
❤️ Server Health & Version
# Health check
python scripts/gotify_client.py health
# Version info
python scripts/gotify_client.py version
📡 Real-Time WebSocket Stream
Subscribe to live messages (requires 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>
Output is one JSON object per received message.
API Key Concepts
- App token (
GOTIFY_APP_TOKEN): for sending messages via/message - Client token (
GOTIFY_CLIENT_TOKEN): for managing apps/clients/messages everywhere else - Token is passed via
X-Gotify-Keyheader (script handles this automatically)
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
GOTIFY_URL not set |
Missing env var | Set GOTIFY_URL=https://your-server |
401 Unauthorized |
Wrong/missing token | Check which token type is needed; verify env var |
403 Forbidden |
Client token used on send | Use app token for /message |
Connection refused |
Server down | Run health to verify |
No app token |
Token not configured | Set GOTIFY_APP_TOKEN or use --token |