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 — npm run manage (no arguments) launches a TUI menu.
• Direct commands — npm run manage <command> for scripting and automation.

After publishing to npm, it is also available as npx ntfy-reverse-proxy or npx nrp.

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, lint, deploy 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 or token. Leave a field blank to keep the current value.
• Remove — Select a server to remove. Fails if any context references it.

Context Submenu

• Add — Prompts for name, type (HTTP or email), interpreter, topic, primary server, selected servers, and visitor info toggle. The context ID (20 lowercase alphanumeric characters) and token (64 mixed-case alphanumeric characters) are auto-generated. Requires at least one server to exist first.
• Edit — Select an existing context, then update individual fields.
• Remove — Select a context to remove.

Commands

server remove <name>

Removes a server definition by name. Fails if any context still references the server in its primary_server or servers list — you will need to update those contexts first.

context remove <name>

Removes a context by name.

validate

Validates the current config file. Checks:

• Schema validation (required fields, correct types)
• Server reference integrity (all primary_server and servers entries point to existing servers)
• No duplicate context IDs

Returns a list of errors if any are found.

generate

Generates a wrangler.toml file from the config. The generated file includes:

• Worker name, main entry point, and compatibility date
• Routes array with {context-id}.{base_domain} patterns for each HTTP context
• Email routing section showing required forwarding addresses for email contexts
• Environment variables (SETTINGS, SERVERS, CONTEXTS) as JSON strings
• KV namespace bindings if a namespace ID is provided

deploy

Runs the full deployment pipeline:

1. Resolves the Cloudflare API token (from .env or interactive prompt).
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. Runs ESLint.
7. Deploys the worker via Wrangler.
8. Configures Cloudflare Email Routing rules for email contexts (if any).
9. 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 config.sample.json to the default config directory as a starting point.