CLI Reference

Use the CLI to manage config.json, validate settings, generate wrangler.toml, and deploy to Cloudflare Workers.

Overview

The CLI manages the config.json file that the Cloudflare Worker reads at runtime. You can run it in two ways:

• Interactive mode — nrp (no arguments) launches a TUI menu.
• Direct commands — nrp <command> for scripting and automation.

ntfy-reverse-proxy and nrp are registered as CLI aliases. To run it once without installing, use npx ntfy-reverse-proxy.

When working inside a clone of the repository, the same CLI is available as npm run manage and npm run manage <command>.

Interactive Menu

When launched without arguments, the CLI presents a menu with these options:

• Manage Servers — Manage ntfy server definitions (submenu: add, edit, remove).
• Manage Contexts — Manage notification contexts (submenu: add, edit, remove).
• Settings — View and update global settings (worker name, base domain, debug output).
• Deploy — Validate config, verify Cloudflare permissions, create KV namespace, generate wrangler.toml, deploy the worker, and configure email routing — all in one step.
• Exit — Exit the CLI.

The interactive menu uses prompts for terminal UI. It walks you through each field with validation.

Server Submenu

• Add — Prompts for name, server URL (must start with https://), and token (must start with tk_).
• Edit — Select an existing server, then update its URL, which starts filled in with the current one, or its token. Leave the token blank to keep the current one.
• Remove — Select a server to remove. Fails if any context references it.

Context Submenu

• Add — Prompts for the type (HTTP or email), name, ID, interpreter, topic, error topic and the errors that notify it, delivery mode, visitor info toggle, primary server, and the servers to use. It ends with an auth token for an HTTP context or an allowed sender for an email context, and it requires at least one server to exist first.
• IDs and tokens — Leaving the ID blank gives an HTTP context a generated 20-character lowercase ID. A manually entered HTTP ID must be a 1–63 character DNS host label made of lowercase letters, digits, and interior hyphens. An email context needs an ID you choose, since it becomes the address's local part. The suggested auth token is a generated 64-character mixed-case string, and clearing it leaves the context without a token.
• Interpreter choices — HTTP contexts offer Plain Text, ntfy JSON, Seerr, Synology DSM, Statuspage.io, Transmission VPN, pfSense Actions, Discord Stonker Bot, and Outpost. Email contexts offer Plain Text, pfSense, and UniFi.
• Edit — Select an existing context, then step through the same fields with the current values filled in. You can keep the ID; choosing a new HTTP ID generates one, while choosing a new email ID prompts for its replacement local part. You can also keep or regenerate an HTTP auth token, add a token to an HTTP context without one, or clear an email context's allowed sender.
• Remove — Select a context to remove.

Commands

server remove <name>

Removes a server definition by name. Fails if the named server does not exist, or if any context still references it in primary_server or servers — you will need to update those contexts first.

context remove <name>

Removes a context by name. Fails if the named context does not exist.

validate

Validates the current config file. Checks:

• Schema validation (required fields, correct types, and no unknown context keys)
• Server reference integrity (all primary_server and servers entries point to existing servers, and each primary_server is in its context's servers)
• No duplicate context IDs

Prints each error it finds, and exits with code 1 when the config is invalid.

generate

Generates a wrangler.toml file from the config and writes it next to your config.json, plus a Worker entry and a copy of the config in .wrangler/ntfy-reverse-proxy/ beside it. The generated wrangler.toml includes:

• Worker name, compatibility date, and main entry pointing to the generated entry, which imports the Worker included with the installed package
• Routes array with {context-id}.{base_domain} patterns for each HTTP context
• Email routing section showing required forwarding addresses for email contexts
• No KV namespace binding, which only deploy adds after it creates or finds the namespace

deploy

Runs the full deployment pipeline:

1. Resolves the Cloudflare API token from CLOUDFLARE_API_TOKEN in the environment or a .env file. When none works, Deploy in the interactive menu prompts for one and saves it to the .env file in your config directory, while nrp deploy stops with an error.
2. Validates config integrity.
3. Verifies Cloudflare API permissions (Workers, KV, and optionally Email Routing).
4. Creates or locates a KV namespace for Statuspage deduplication.
5. Generates wrangler.toml.
6. Deploys the worker via Wrangler.
7. Configures Cloudflare Email Routing rules for email contexts (if any).
8. Prints a summary of deployed URLs and email addresses.

Config File Resolution

The CLI looks for config files in this order:

1. Current working directory.
2. Project root directory.
3. Platform-specific config directory.

If no config.json is found, the CLI copies the starter template bundled with the npm package to the default config directory. When nrp opens the interactive menu and finds config.json in more than one of these places, it asks which one to use, while commands use the first one found.