CLI Reference

The pab CLI provides a pragmatic interface for managing Technitium DNS blocking configurations via the command line and interactive TUI.

Global Flag

All pab commands respect this global flag:

• --config, -c <path>: Path to your Technitium dnsApp.config file (default: dnsApp.config in current directory)

Example:

pab map --ip 192.0.2.50 --group Kids --config /etc/technitium/dnsApp.config

Interactive Mode: The pab Command

Running pab with no arguments (in a terminal) launches the interactive TUI dashboard.

What it does: Opens a full-screen terminal UI where you can search, filter, and view your client IP mappings and blocking groups in real time.

Syntax:

pab

When to use: Exploring your configuration, searching for specific clients, or viewing group details interactively.

Interactive Mode Features:

• Search clients by IP or group name
• List all configured groups with device counts
• View group details (allowed domains, blocked domains, blocklists)
• Tab-complete slash commands for power-user efficiency
• Exit via /exit or Ctrl+C

See also: Interactive Mode — Slash Commands and Tab Completion in the User Guide.

Command: pab init

Bootstrap a local dnsApp.config from a Technitium server (or a blank template).

What it does: Resolves your Technitium credentials, fetches the live Advanced Blocking configuration from the server, and previews it. If the server has no existing configuration (a fresh Technitium instance), pab init falls back to a minimal template instead of leaving you with nothing. If two or more nodes are configured, it also checks that they agree on their current configuration before proceeding — it never auto-merges disagreeing nodes. Nothing is written to disk until you explicitly confirm. If a local dnsApp.config already exists, pab init diffs it against the fetched/template configuration before asking to overwrite, so it never silently clobbers an existing file.

Syntax:

pab init [--node <name>] [-f, --force] [--json]

Flags:

• --node <name>: Node to fetch from (and, if two or more configured nodes disagree on their current configuration, the explicit source of truth)
• -f, --force: Write the resolved configuration without an interactive confirmation prompt
• --json: Print the resolved configuration as JSON and exit without writing or prompting

Examples:

First-time setup, fetching from your only configured node:

pab init

Fetch from a specific node when more than one is configured:

pab init --node prod

Non-interactive/scripted preview (fails clearly if no credentials are resolvable — does not prompt):

pab init --json > dnsApp.config.preview.json

Re-sync and overwrite an existing local dnsApp.config without a confirmation prompt:

pab init -f

When to use: The very first time you set up pab against a running Technitium server, or any time you want to re-sync your local dnsApp.config with what’s actually deployed.

Credential resolution: Same rule as pab deploy/pab verify — one node via TECHNITIUM_URL/TECHNITIUM_TOKEN, two or more via ~/.config/pab/secrets.json. If neither is set, pab init prompts for them interactively (unless --json is set, which errors instead of prompting): for a single node it prints the export lines for you to add to your shell profile; for two or more nodes it writes secrets.json (chmod 600, set at creation) for you. See Installation & Credentials in the User Guide for the full picture.

Command: pab map

Map (or reassign) a client IP to a blocking group.

What it does: Adds or updates a client IP mapping in your configuration. The IP is validated for correct format (IPv4, IPv6, or CIDR). Configuration is validated before being written to disk.

Syntax:

pab map --ip <IP> --group <GROUP>

Flags:

• --ip <IP> (required): Client IP address, CIDR range, or hostname
• --group <GROUP> (required): Target blocking group name (must exist in your configuration)

Examples:

Map a single device to the Kids group:

pab map --ip 192.0.2.50 --group Kids

Map a CIDR range to IoT devices:

pab map --ip 203.0.113.0/28 --group IoT

Reassign a device to a different group:

pab map --ip 198.51.100.100 --group Do-Not-Block

When to use: Programmatic assignment of devices (e.g., in CI/CD pipelines), automation scripts, or when you want command-line confirmation of mappings.

Command: pab unmap

Remove a client IP mapping from the configuration.

What it does: Deletes a client IP mapping. Returns an error if the IP is not currently mapped. Configuration is validated after removal.

Syntax:

pab unmap --ip <IP>

Flags:

• --ip <IP> (required): Client IP address or CIDR range to remove

Examples:

Remove a single device:

pab unmap --ip 192.0.2.50

Remove a CIDR range:

pab unmap --ip 203.0.113.0/28

When to use: Deprovisioning devices, automating cleanup of old device mappings, or removing test IPs before deployment.

Command: pab deploy

Sync your validated configuration to Technitium DNS server API nodes.

What it does: Sends your local configuration to one or more Technitium instances via the Web API. Supports dry-run preview, confirmation prompts, and multi-node deployments. No DNS queries are interrupted during deployment.

Syntax:

pab deploy [--dry-run] [-f, --force] [--node <name>]

Flags:

• --dry-run: Preview changes (validation + structural diff) without applying. Shows what would change on the target node(s).
• -f, --force: Deploy to all nodes without confirmation prompt (useful for automated/CI deployments).
• --node <name>: Deploy to a specific node by name instead of all configured nodes.

Examples:

Preview changes before deploying:

pab deploy --dry-run

Deploy to all configured Technitium nodes with confirmation:

pab deploy

Deploy to a single node without confirmation:

pab deploy -f --node production

Deploy to all nodes without confirmation (for automation):

pab deploy -f

When to use: Pushing validated configurations to your Technitium instances, verifying changes in dry-run mode before committing, or automating deployments in GitOps workflows.

Configuration Discovery: pab deploy (and pab init/pab verify) resolve Technitium node URLs and API tokens from:

1. One node: environment variables TECHNITIUM_URL and TECHNITIUM_TOKEN (registered internally as "default")
2. Two or more nodes: ~/.config/pab/secrets.json (must have chmod 600 permissions) — there is no multi-node environment variable pattern

See Installation & Credentials in the User Guide for the full setup, including writing secrets.json from a CI secret.

Command: pab verify

Query a node’s live DNS resolver to confirm a domain is actually being blocked.

What it does: Sends a live DNS query for --domain directly to the target Technitium node’s resolver (bypassing your system resolver/cache) and compares the response against the configured blocking behavior of the group --domain belongs to (blockAsNxDomain/blockingAddresses in your local dnsApp.config). This confirms blocking actually took effect on the server — not just that pab deploy successfully sent a config to the API.

Syntax:

pab verify --domain <domain> [--node <name>] [--group <name>] [--port <port>] [--json]

Flags:

• --domain <domain> (required): Domain to test-query against the node’s DNS resolver
• --node <name>: Node to query (required when more than one node is configured — pab verify queries exactly one node, unlike pab deploy’s fan-out)
• --group <name>: Explicit group to verify against, for domains not covered by a literal blockedDomains/blockedRegex entry (e.g. domains only blocked indirectly via a remote block-list URL, which pab verify does not fetch or search)
• --port <port> (default: 53): DNS port to query on the target node
• --json: Print the verification result as JSON

Examples:

Confirm a domain is blocked right after deploying:

pab deploy -f && pab verify --domain ads.example.com

Verify against a specific node when more than one is configured:

pab verify --domain ads.example.com --node prod

Verify a domain only covered by a remote block-list URL, specifying its group explicitly:

pab verify --domain doubleclick.net --group Default

Machine-readable result for scripting:

pab verify --domain ads.example.com --json

When to use: Right after pab deploy, to confirm blocking took effect on the live server. Exits non-zero unless the result is exactly blocked, so it’s safe to chain directly in CI/CD after pab deploy.

A note on results: pab verify reports one of four outcomes — blocked, not-blocked, inconclusive (e.g. a sinkhole-style group with no blockingAddresses configured, so pab can’t compare the live response against anything), or error (the DNS query itself failed). Only blocked is treated as a confirmed pass.

Tips for CLI Integration

Bootstrap Before You Map: No local dnsApp.config yet? Run pab init first — it fetches your server’s live configuration (or a starter template if there is none) and writes it only after you confirm:

pab init

Dry-Run Before Deploy: Always run --dry-run first to see what will change:

pab deploy --dry-run
pab deploy -f

Confirm It Worked: After deploying, chain pab verify to confirm blocking actually took effect on the server, not just that the API accepted your config:

pab deploy -f && pab verify --domain ads.example.com

Automation with -f, --force: Use -f or --force in CI/CD pipelines to skip interactive prompts:

pab map --ip 192.0.2.100 --group Kids
pab deploy -f

Error Handling: All commands exit with non-zero status on validation failure, making them safe for shell scripts:

pab map --ip 192.0.2.100 --group Kids || exit 1
pab deploy --dry-run || exit 1

See Also

• User Guide: Setup, credentials, quickstart, and interactive mode
• Installation: Install the CLI