README.md
January 4, 2026 · View on GitHub
nextdns-manager
CLI and Web tools for managing NextDNS profiles
Made by @abhijithvijayan
Table of Contents
- Features
- Installation
- Usage
- Web App
- Fields Copied
- Schema Validation
- API Documentation
- Issues
- License
Features
Web App Available: apps.nextdns.abhijithvijayan.in - No installation required!
- Manage domains across all profiles - Add, remove, enable, or disable domains from allowlist/denylist across all profiles with a single command
- Sync denylist/allowlist across profiles - Automatically sync domains across all profiles using majority voting
- Diff profiles - Visualize differences between NextDNS profiles in a table format
- Clone profiles - Copy entire NextDNS profiles including:
- Security settings (threat intelligence, safe browsing, cryptojacking protection, etc.)
- Privacy settings (blocklists, native tracking blockers)
- Parental control settings (safe search, services, categories)
- Denylist and allowlist entries
- Custom rewrites
- General settings (logs, block page, performance, web3)
- Automatic verification of cloned profiles
- Schema validation to detect API changes
Installation
Requires Node.js 20 or later.
npm install -g nextdns-manager-cli
Or run directly with npx:
npx nextdns-manager-cli <command> [options]
Usage
Manage Domain
Add, remove, enable, or disable a domain in the allowlist or denylist across all profiles.
nextdns-manager manage -k <API_KEY> -d <DOMAIN> -l <LIST> [-a <ACTION>] [-p <PROFILES>]
Arguments
| Argument | Description |
|---|---|
-k, --api-key | NextDNS API key |
-d, --domain | Domain to manage (e.g., example.com) |
-l, --list | Target list: allowlist or denylist |
-a, --action | Action: add (default), remove, enable, or disable |
-p, --profiles | Specific profile IDs to target (default: all profiles) |
Examples
# Add domain to denylist across all profiles
nextdns-manager manage -k "your-api-key" -d "malware.com" -l denylist
# Add domain to allowlist
nextdns-manager manage -k "your-api-key" -d "trusted.com" -l allowlist
# Disable a domain (keep it but inactive)
nextdns-manager manage -k "your-api-key" -d "example.com" -l denylist -a disable
# Enable a previously disabled domain
nextdns-manager manage -k "your-api-key" -d "example.com" -l denylist -a enable
# Remove a domain
nextdns-manager manage -k "your-api-key" -d "example.com" -l denylist -a remove
# Target specific profiles only
nextdns-manager manage -k "your-api-key" -d "example.com" -l denylist -p abc123 def456
Sync Lists
Synchronize denylist and allowlist domains across all NextDNS profiles using majority voting.
nextdns-manager sync -k <API_KEY> [-l <LIST>] [-p <PROFILES>] [--dry-run]
Arguments
| Argument | Description |
|---|---|
-k, --api-key | NextDNS API key |
-l, --list | Which list to sync: allowlist, denylist, or both (default: both) |
-p, --profiles | Specific profile IDs to sync (default: all profiles) |
--dry-run | Show what would be synced without making changes |
How It Works
- Fetches all domains from denylist/allowlist across all profiles
- For each domain, determines the canonical state using majority voting (enabled wins ties)
- Adds missing domains to profiles that don't have them
- Updates domain status where it differs from the canonical state
Examples
# Sync both lists across all profiles
nextdns-manager sync -k "your-api-key"
# Preview changes without applying (dry run)
nextdns-manager sync -k "your-api-key" --dry-run
# Sync only denylist
nextdns-manager sync -k "your-api-key" -l denylist
# Sync specific profiles only
nextdns-manager sync -k "your-api-key" -p abc123 def456
Diff Profiles
Visualize differences between NextDNS profiles in a table format.
nextdns-manager diff -k <API_KEY> [-p <PROFILES>] [-s <SECTION>] [--diff-only]
Arguments
| Argument | Description |
|---|---|
-k, --api-key | NextDNS API key |
-p, --profiles | Specific profile IDs to compare (default: all profiles) |
-s, --section | Section to compare: all, lists, security, privacy, parental, settings (default: all) |
--diff-only | Only show rows with differences |
Examples
# Compare all profiles across all sections
nextdns-manager diff -k "your-api-key"
# Show only differences
nextdns-manager diff -k "your-api-key" --diff-only
# Compare only security settings
nextdns-manager diff -k "your-api-key" -s security
# Compare specific profiles
nextdns-manager diff -k "your-api-key" -p abc123 def456
Copy Profile
Clone an entire NextDNS profile to a new profile.
nextdns-manager copy -s <SOURCE_API_KEY> -d <DEST_API_KEY> -p <PROFILE_ID> [-f]
Arguments
| Argument | Description |
|---|---|
-s, --source-key | API key for the source NextDNS account |
-d, --dest-key | API key for the destination NextDNS account |
-p, --profile-id | Profile ID to clone from the source account |
-f, --force | Force copy even if unknown API fields are detected |
Example
nextdns-manager copy -s "source-api-key" -d "dest-api-key" -p "a1b2c3"
Getting Your API Key
- Log in to your NextDNS account
- Navigate to Account settings
- Generate or copy your API key
Web App
A Next.js web application is also available that provides a graphical interface for all CLI features.
Live Demo: apps.nextdns.abhijithvijayan.in
Features
- Manage Domain - Add, remove, enable, or disable domains from allowlist/denylist with a visual interface
- Sync Lists - Sync domains across profiles with real-time progress tracking and dry-run preview
- Diff Profiles - Compare profiles side-by-side with color-coded differences
- Copy Profile - Clone profiles between accounts with visual feedback
Self-Hosting
cd source/web
npm install
npm run dev
The web app stores your API key locally in your browser - it's never sent to any server other than NextDNS.
See the Web App README for detailed setup, deployment (Cloudflare, Vercel, etc.), and configuration instructions.
Fields Copied
Security
| API Field | NextDNS Setting |
|---|---|
threatIntelligenceFeeds | Threat Intelligence Feeds |
aiThreatDetection | AI-Driven Threat Detection |
googleSafeBrowsing | Google Safe Browsing |
cryptojacking | Cryptojacking Protection |
dnsRebinding | DNS Rebinding Protection |
idnHomographs | IDN Homograph Attacks Protection |
typosquatting | Typosquatting Protection |
dga | Domain Generation Algorithms (DGAs) Protection |
nrd | Block Newly Registered Domains (NRDs) |
ddns | Block Dynamic DNS Hostnames |
parking | Block Parked Domains |
csam | Block Child Sexual Abuse Material |
tlds | Block Top-Level Domains (TLDs) |
Privacy
| API Field | NextDNS Setting |
|---|---|
blocklists | Blocklists (NextDNS, Steven Black, AdGuard, OISD, etc.) |
natives | Native Tracking Protection (Windows, Apple, Samsung, etc.) |
disguisedTrackers | Block Disguised Third-Party Trackers |
allowAffiliate | Allow Affiliate & Tracking Links |
Parental Control
| API Field | NextDNS Setting |
|---|---|
services | Websites, Apps & Games (TikTok, Snapchat, Roblox, etc.) |
categories | Categories (Porn, Gambling, Dating, Piracy) |
safeSearch | SafeSearch |
youtubeRestrictedMode | YouTube Restricted Mode |
blockBypass | Block Bypass Methods |
Settings
| API Field | NextDNS Setting |
|---|---|
logs | Logs (enabled, privacy adjustments, retention, location) |
blockPage | Block Page |
performance | Performance (EDNS Client Subnet, Cache Boost, CNAME Flattening) |
bav | Bypass Age Verification |
web3 | Web3 (ENS, Unstoppable Domains, Handshake, IPFS) |
Other
| Section | Description |
|---|---|
| Denylist | All entries with active status |
| Allowlist | All entries with active status |
| Rewrites | All custom DNS rewrites |
Fields NOT Copied
These fields cannot be copied via the API and require manual configuration:
| Field | NextDNS Setting | Reason |
|---|---|---|
id | Profile ID | Auto-generated by NextDNS for new profile |
fingerprint | Profile fingerprint | Auto-generated by NextDNS for new profile |
setup | Setup (DNS IPs, linked IP) | Auto-generated by NextDNS for new profile |
parentalControl.recreation | Recreation Time | Not supported by API for write operations |
Schema Validation
The tools validate the API response against known fields. If NextDNS adds new features, you'll see a warning:
WARNING: Unknown fields detected in API response!
This script may be outdated and missing new NextDNS features.
- Unknown field(s) at 'security': newFeature
To proceed anyway, use the --force flag.
API Documentation
For more information about the NextDNS API, see the official API documentation.
Issues
Looking to contribute? Look for the Good First Issue label.
Bugs
Please file an issue here for bugs, missing documentation, or unexpected behavior.
License
MIT © Abhijith Vijayan