CLI Reference

Manage every alias, destination, and setting from the terminal, either through a guided menu or with direct commands you can script.

Why Use This Command?

1. Opens a guided menu with no arguments so you never need to remember flags for everyday changes.
2. Offers direct commands for every action so you can script alias creation and deploys.
3. Validates the config on every change so broken references are caught before they reach Cloudflare.

Requirements

• Node.js runtime — v22 or v24.
• A Cloudflare API token — Only needed for deploy. See Deployment for the required permissions.

Usage

mailmask and mm are the same command. Inside a clone of the repository, npm run manage runs the CLI from source.

Interactive Menu

Running mm with no arguments opens a menu with these sections:

• Manage Aliases — Create an alias, list them with their status, or modify one (enable, disable, change expiry, or remove).
• Manage Destinations — Add, list, or remove a destination inbox.
• Manage Notifiers — Add an ntfy topic or a Reverse Proxy for ntfy context, list notifiers, or remove one.
• Settings — Edit the Worker name, base domain, unknown alias action, subaddressing, and alias headers.
• Deploy — Run the full deploy, with guided API token setup.
• Exit — Close the CLI.

Alias Commands

alias add

Create an alias and save it to the config.

alias list

Print one line per alias with its full address, destination, status, and label, separated by tabs.

alias enable <address> and alias disable <address>

Turn an alias on or off. A disabled alias refuses all mail but keeps its address reserved.

alias expire <address> <when>

Set when an alias expires. <when> accepts 30m, 12h, 7d, 4w, an ISO date, or never to remove the expiry.

alias remove <address>

Delete an alias from the config.

Destination Commands

destination add <name> <email>

Add a destination inbox. Cloudflare emails it a verification link on the next deploy.

destination list

Print each destination name and address, separated by tabs.

destination remove <name>

Remove a destination. The command refuses while any alias still forwards to it, or while it is the default_destination.

Notifier Commands

notifier add-ntfy <name>

Notify an ntfy topic directly. Requires --server <url>, --topic <topic>, and --token <tk_...>.

notifier add-reverse-proxy <name>

Notify a Reverse Proxy for ntfy context. Requires --url <url>; add --token <token> when the context requires one.

notifier list

Print each notifier name and type, separated by tabs.

notifier remove <name>

Remove a notifier.

Project Commands

validate

Check the config against the schema and its cross-references, and print every problem found.

generate

Write wrangler.toml from the config without deploying. Useful for inspecting exactly what the Worker receives.

deploy

Validate, register destinations, publish the Worker, and point the catch-all at it. See Deployment for each step.

The direct command reads CLOUDFLARE_API_TOKEN from the environment or a .env file (in the working directory, project root, or config directory). It exits with a non-zero code instead of prompting when the token is missing or invalid.