CLI reference.

connect displays an existing connection without silently replacing it. create explicitly asks for a new Topic. send publishes a notification. ask supports confirmation, choices, and text. Use --help for the exact syntax supported by your installed build.

ntfyx connect
ntfyx create
ntfyx send "Done"
ntfyx ask "Continue?" --allow-deny
ntfyx result REQUEST_ID
ntfyx doctor

Reading result is read-only. It is not permission to repeat an action. A verified answer must pass a one-time claim and a durable local ledger before resuming the original invocation. Retry ambiguous delivery with the original ID and exact signed bytes. Never turn a timeout, cancellation, invalid answer, or network error into Allow.

Use structured JSON and the installed CLI help for automation. A successful result read is separate from permission to execute an action.

ask owns its request and applies the keep-pending rule when its wait ends. result only observes and does not cancel the request when a wait ends. stdin data must remain within the 16 KiB payload limit. Claude permission context that exceeds the limit returns to the terminal; it must never be truncated and remotely approved.

Credentials live in restricted local files. Compiled binaries must not auto-load project .env or bunfig files. Run from untrusted working directories only with the hardened released executable. Do not paste pairing links, recovery codes, tokens, or content into diagnostic reports.

CLI 0.1.3 and current clients group related messages into Sessions within a Topic. Confirm or choose on the original message; select Reply for a quoted text answer. CLI 0.1.3 includes --session-id and --session-name; run ntfyx upgrade to update. Read the guide for examples, standalone-message defaults and availability.

• Sessions and message replies

CLI 0.1.3+ supports --session-id and --session-name on send and ask, with NTFYX_SESSION_ID and NTFYX_SESSION_NAME as defaults. Keep the same ID for one task; without an ID each message starts a separate conversation.

ntfyx send "Build passed" --session-id release-24 --session-name "Release v2.4"

• Session guide

CLI 0.2.0 can manage the same My Monitor items as your phone. Open My Monitor in the app once, then authorize your paired Source. Your primary phone must approve the exact monitor read/write scope. The default grant lasts 24 hours; --expires accepts 5 minutes to 24 hours. It ends when it expires, you revoke it, the Source is disconnected, or phone/root authority changes.

Phone and root private keys stay on the phone. Only this authorization question and answer are explicitly disclosed to the service for verification; ordinary agent exchanges keep their existing encryption.

ntfyx monitor authorize
ntfyx monitor add --name "My service" --url https://example.com/health --dry-run
ntfyx monitor add --name "My service" --url https://example.com/health
ntfyx monitor list
ntfyx monitor show MONITOR_ID
ntfyx monitor update MONITOR_ID --json-field ok --equals true
ntfyx monitor test MONITOR_ID
ntfyx monitor pause MONITOR_ID
ntfyx monitor resume MONITOR_ID
ntfyx monitor revoke

Use capabilities or help COMMAND --json for command schemas and authorization requirements. Unsupported command options fail before remote work; send --dry-run is rejected. topics and sources list only local connection profiles. requests list/show read this Source's encrypted local request ledger without claiming replies; use result REQUEST_ID for current server status.

marketplace list/show verify the public catalogue signature and do not subscribe you to anything. MCP provides capability discovery and the monitor authorization, management and test tools.

ntfyx capabilities
ntfyx help monitor add --json
ntfyx requests list --limit 20
ntfyx requests show REQUEST_ID
ntfyx marketplace list

monitor add/update accept a complete configuration through --stdin; updates made with flags preserve unspecified fields. --dry-run returns a plan without changing server state. --operation-id accepts a stable base64url ID of 22–80 characters. Reuse it with exact input after an uncertain response; the protected local ledger retains the original intent.

--generation checks the record version and rejects concurrent changes instead of overwriting them. monitor test/preview return exit 1 for an unhealthy observation; their JSON explains the result. Reads do not create monitor alerts. Keep response samples as untrusted data, not agent instructions.

CLI 0.3.0 and the local MCP tools can manage independent wh_ sending keys. First prepare HTTPS Push on the primary phone, pair your Source, then request separate webhook management permission. Your phone must approve the fixed Topic and scope; monitor permission does not grant webhook management. The management grant lasts up to 24 hours.

A created key can last until its owner Source expires, which can be longer than that grant.

ntfyx webhook authorize --async --no-input --expires 24h --json
ntfyx webhook auth-status AUTHORIZATION_ID --json
ntfyx webhook create --name "Deploy alerts" --url-file ./private-webhook-url.txt --json
ntfyx webhook list --json
ntfyx webhook show WEBHOOK_ID --json
ntfyx webhook update WEBHOOK_ID --name "Production deploys" --dry-run --json
ntfyx webhook rotate WEBHOOK_ID --url-file ./next-private-webhook-url.txt --json
ntfyx webhook disable WEBHOOK_ID --json
ntfyx webhook enable WEBHOOK_ID --json
ntfyx webhook delete WEBHOOK_ID --json
ntfyx webhook revoke --json

webhook revoke ends the current Source's management grant; it does not disable keys already created. Use disable or delete to stop an individual URL. Owner Source revocation or expiry, a primary-phone key/identity change, or a root-version change invalidates its keys. Pausing the parent HTTPS sender pauses its children and can be resumed with the same parent token.

Rotating the parent token invalidates old child keys. Each Inbox supports up to 100 nondeleted keys. At capacity, the service can reclaim permanently invalid keys; revoked management grants or a recoverable parent pause do not cause reclamation. Keys share the existing HTTPS sender's 60 requests per minute admission limit.

Ordinary message limits also apply: 30 new messages per minute and 10 per 2 seconds per Source.

Generic mode authenticates the private bearer URL. For a child key, explicitly choose github or standard and provide a separate private verification-secret file. GitHub checks X-Hub-Signature-256 against the raw request body; it does not sign the delivery ID or timestamp. Standard Webhooks binds the delivery ID, timestamp and raw body, with a 300-second past/future window.

A configured signature mode rejects missing or invalid signatures; a header alone never enables a mode or permits a downgrade. Standard Webhooks is a community convention, not a universal payload format.

ntfyx webhook create --name "GitHub events" --signature-mode github \
  --verification-secret-file ./github-webhook-secret.txt \
  --url-file ./private-github-url.txt --json

• GitHub signature validation
• Standard Webhooks specification

Windows x64 / ARM64, macOS Apple silicon / Intel and Linux glibc x64 / ARM64 provide the full CLI and local MCP, including messages, questions, phone-authorized My Monitor and webhook management. Native host permission approvals have separate adapter, operating-system, version and tool requirements. On Windows, use direct CLI setup or local MCP.

Claude Code hooks require 2.1.139+; an older or unknown version gets MCP only. Codex on Windows provides MCP questions without automatic hooks. The marketplace plugin uses POSIX shell hooks; use direct setup on Windows. Native tool permission approvals retain their separate platform and host policy.

Runtime requirements: Windows 10 1809+, macOS 13+, and glibc-based Linux. x64 CPUs require Nehalem / SSE4.2 or newer; AVX2 is not required. These are the official requirements for the embedded Bun 1.4.2 runtime; tested systems are recorded separately.

• Bun 1.4.2 official system and CPU requirements

Run the official installer in PowerShell without administrator rights. It selects the native x64 or ARM64 download and verifies the Ntfyx release signature and exact hash. Manual script or ZIP downloads and npm with an existing Node.js 24 installation are alternatives in the detailed guide. The release signature is not a claim of Windows Authenticode signing.

irm https://ntfyx.me/install.ps1 | iex
ntfyx version --json
ntfyx connect

install.sh is for macOS and Linux; do not run its bash command as a PowerShell installer. npm requires Node.js 24 and installs the current wrapper on all six listed platforms, verifying the signed native binary. Standalone installations use ntfyx upgrade; npm owns updates for npm installations.

curl -fsSL https://ntfyx.me/install.sh | bash

# npm / Node.js 24
npm install -g ntfyx@0.6.1
ntfyx version --json
ntfyx connect

CLI 0.6.0 independently sends ordinary text, Markdown and native metric/table/chart messages, with local validation before sending. See the guide for receiver version requirements and store availability.

• Rich-message formats and complete example

Anyone with an existing public Topic ID or link can read and send without an account, pairing or key. The name and messages are readable by the service and anyone with the link; keep passwords, private logs and approval requests out of it. Public messages support text, Markdown and lightweight rich content, without answers, approvals or Call reminders.

Use a protected Topic for private messages, authenticated senders or signed answers.

• Public Topics: send your first notification without pairing