Skip to content
NextDNS Blocker

category

The category command group manages domain categories - groups of domains that share the same schedule and unblock delay.

Overview

Section titled “Overview”

Categories simplify configuration by letting you define settings once and apply them to multiple domains.

Subcommands

Section titled “Subcommands”
SubcommandDescription
listList all categories
showShow category details
createCreate a new category
addAdd domain to category
removeRemove domain from category
deleteDelete a category

category list

Section titled “category list”

List all configured categories.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category list

Output

Section titled “Output”
Categories (3)


ID              Domains   Delay    Description
──────────────────────────────────────────────────────────────
social-media    4         4h       Social networks
gambling        3         never    Betting and casino sites
streaming       4         2h       Video streaming

No Categories

Section titled “No Categories”
No categories configured


Create a category:
  nextdns-blocker category create <id> [-d "description"]

category show

Section titled “category show”

Show detailed information about a category.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category show CATEGORY_ID

Example

Section titled “Example”
Terminal window
nextdns-blocker category show social-media

Output

Section titled “Output”
Category: social-media
━━━━━━━━━━━━━━━━━━━━━━


Description: Social networks
Unblock Delay: 4h


Schedule:
  Mon-Fri: 12:00-13:00, 18:00-22:00
  Sat-Sun: 10:00-23:00


Domains (4):
  - instagram.com
  - tiktok.com
  - snapchat.com
  - twitter.com

Category Not Found

Section titled “Category Not Found”
Terminal window
nextdns-blocker category show nonexistent

Output:

Error: Category 'nonexistent' not found

Case Insensitive

Section titled “Case Insensitive”

Category IDs are case-insensitive for lookups:

Terminal window
nextdns-blocker category show SOCIAL-MEDIA
# Works the same as: category show social-media

category create

Section titled “category create”

Create a new category.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category create CATEGORY_ID [OPTIONS]

Options

Section titled “Options”
OptionDescription
-d, --description TEXTDescription for the category
--delay TEXTUnblock delay (e.g., 30m, 4h, 1d, never)

Examples

Section titled “Examples”

Basic creation:

Terminal window
nextdns-blocker category create gaming

With description:

Terminal window
nextdns-blocker category create gaming -d "Gaming platforms"

With delay:

Terminal window
nextdns-blocker category create gambling --delay never

Full options:

Terminal window
nextdns-blocker category create streaming -d "Video streaming" --delay 2h

Output

Section titled “Output”
Created category 'gaming'


Add domains with:
  nextdns-blocker category add gaming <domain>

Validation Errors

Section titled “Validation Errors”

Invalid ID format:

Terminal window
nextdns-blocker category create Invalid-ID
Error: Invalid category ID 'Invalid-ID'
Must start with lowercase letter, contain only lowercase letters, numbers, and hyphens

Category exists:

Terminal window
nextdns-blocker category create social-media
Error: Category 'social-media' already exists

Invalid delay:

Terminal window
nextdns-blocker category create test --delay invalid
Error: Invalid delay format 'invalid'
Valid formats: 0, 30m, 1h, 4h, 24h, 1d, never

ID Requirements

Section titled “ID Requirements”
  • Must start with a lowercase letter
  • Only lowercase letters, numbers, and hyphens
  • Maximum 50 characters

Valid: social-media, gaming, work-tools, category123

Invalid: Social-Media, 123gaming, -category, gaming_sites

category add

Section titled “category add”

Add a domain to a category.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category add CATEGORY_ID DOMAIN

Example

Section titled “Example”
Terminal window
nextdns-blocker category add social-media reddit.com

Output

Section titled “Output”
Added 'reddit.com' to category 'social-media'

Validation Errors

Section titled “Validation Errors”

Domain already in category:

Terminal window
nextdns-blocker category add social-media facebook.com
Domain 'facebook.com' already exists in category 'social-media'

Invalid domain format:

Terminal window
nextdns-blocker category add social-media "invalid domain!"
Error: Invalid domain format 'invalid domain!'

Category not found:

Terminal window
nextdns-blocker category add nonexistent test.com
Error: Category 'nonexistent' not found

Panic Mode

Section titled “Panic Mode”

Adding domains is blocked during panic mode:

Terminal window
nextdns-blocker category add social-media test.com
Error: Cannot modify categories during panic mode

category remove

Section titled “category remove”

Remove a domain from a category.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category remove CATEGORY_ID DOMAIN [OPTIONS]

Options

Section titled “Options”
OptionDescription
-y, --yesSkip confirmation prompt

Example

Section titled “Example”
Terminal window
nextdns-blocker category remove social-media reddit.com

Output

Section titled “Output”
Remove 'reddit.com' from category 'social-media'? [y/N]: y
Removed 'reddit.com' from category 'social-media'

Skip Confirmation

Section titled “Skip Confirmation”
Terminal window
nextdns-blocker category remove social-media reddit.com -y

Validation Errors

Section titled “Validation Errors”

Domain not in category:

Terminal window
nextdns-blocker category remove social-media unknown.com
Error: Domain 'unknown.com' not found in category 'social-media'

category delete

Section titled “category delete”

Delete a category entirely.

Usage

Section titled “Usage”
Terminal window
nextdns-blocker category delete CATEGORY_ID [OPTIONS]

Options

Section titled “Options”
OptionDescription
-y, --yesSkip confirmation prompt

Example

Section titled “Example”
Terminal window
nextdns-blocker category delete streaming

Output

Section titled “Output”
Delete category 'streaming'? (2 domains will be removed) [y/N]: y
Deleted category 'streaming'

Skip Confirmation

Section titled “Skip Confirmation”
Terminal window
nextdns-blocker category delete streaming -y

Validation Errors

Section titled “Validation Errors”

Category not found:

Terminal window
nextdns-blocker category delete nonexistent
Error: Category 'nonexistent' not found

Panic Mode

Section titled “Panic Mode”

Deleting categories is blocked during panic mode:

Terminal window
nextdns-blocker category delete gaming -y
Error: Cannot modify categories during panic mode

Workflow Examples

Section titled “Workflow Examples”

Set Up Social Media Blocking

Section titled “Set Up Social Media Blocking”
Terminal window
# Create the category
nextdns-blocker category create social-media -d "Social networks" --delay 4h


# Add domains
nextdns-blocker category add social-media facebook.com
nextdns-blocker category add social-media instagram.com
nextdns-blocker category add social-media twitter.com
nextdns-blocker category add social-media tiktok.com


# Verify
nextdns-blocker category show social-media


# Edit config to add schedule
nextdns-blocker config edit

Reorganize Domains

Section titled “Reorganize Domains”
Terminal window
# List current categories
nextdns-blocker category list


# Move domain from one category to another
nextdns-blocker category remove streaming youtube.com -y
nextdns-blocker category add social-media youtube.com


# Verify
nextdns-blocker category show social-media

Clean Up Categories

Section titled “Clean Up Categories”
Terminal window
# Remove unused domains
nextdns-blocker category remove gaming oldgame.com -y


# Delete empty category
nextdns-blocker category delete old-category -y
Section titled “Related”