gotify

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 token from create-app is 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-Key header (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