A command-line interface for AdGuard Home — the network-wide ad and tracker blocker that runs as a self-hosted DNS sinkhole. This CLI wraps the full AdGuard Home REST API so you can manage your DNS filtering, parental controls, safe browsing, DHCP server, TLS certificates, filter lists, DNS rewrites, client rules, and query logs from a terminal or AI agent.
Key capabilities:
- DNS filtering — manage blocklists, custom filter rules, per-client access controls, and blocked services (YouTube, Facebook, TikTok, etc.)
- Local sync & offline search —
sync pulls all data into a local SQLite database for instant full-text search, analytics, and health reporting without hitting the API
- DNS health dashboard —
health summarizes protection status, block rate, top blocked domains, stale data detection, and query volume trends
- Parental & safe browsing controls — enable/disable safe search, safe browsing (malware/phishing), and parental filtering from the command line
- DHCP management — configure the built-in DHCP server, manage static leases, check for conflicts
- TLS & encryption — configure DoH/DoT/DoQ, validate TLS certificates, generate Apple mobile config profiles
- Real-time monitoring —
tail streams live DNS query changes; analytics runs aggregate queries on synced data
- Agent-ready —
--agent flag sets JSON output, compact mode, no-color, and no-prompts in one flag for AI agent workflows
Printed by @e-jung (Eric Jung).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export ADGUARD_HOME_USERNAME="<paste-your-key>"
You can also persist this in your config file at ~/.config/adguard-home-pp-cli/config.toml.
3. Verify Setup
adguard-home-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
adguard-home-pp-cli access list
Usage
Run adguard-home-pp-cli --help for the full command reference and flag list.
Commands
access
Manage access
adguard-home-pp-cli access list - List (dis)allowed clients, blocked hosts, etc.
adguard-home-pp-cli access set - Set (dis)allowed clients, blocked hosts, etc.
adguard-home-profile
Manage adguard home profile
adguard-home-pp-cli adguard-home-profile get - Get
adguard-home-pp-cli adguard-home-profile update - Updates current user info
apple
Manage apple
adguard-home-pp-cli apple mobile-config-do-h - Get DNS over HTTPS .mobileconfig.
adguard-home-pp-cli apple mobile-config-do-t - Get DNS over TLS .mobileconfig.
blocked-services
Blocked services controls
adguard-home-pp-cli blocked-services all - Get available services to use for blocking
adguard-home-pp-cli blocked-services available-services - Deprecated: Use GET /blocked_services/all instead.
adguard-home-pp-cli blocked-services list - Deprecated: Use GET /blocked_services/get instead.
adguard-home-pp-cli blocked-services schedule - Get blocked services
adguard-home-pp-cli blocked-services schedule-update - Update blocked services
adguard-home-pp-cli blocked-services set - Deprecated: Use PUT /blocked_services/update instead.
cache-clear
Manage cache clear
adguard-home-pp-cli cache-clear - Clear DNS cache
clients
Clients list operations
adguard-home-pp-cli clients add - Add a new client
adguard-home-pp-cli clients delete - Remove a client
adguard-home-pp-cli clients find - Get information about clients by their IP addresses or ClientIDs.
adguard-home-pp-cli clients search - Retrieve information about clients by performing an exact match search using IP addresses, CIDRs, MAC addresses, or ClientIDs.
adguard-home-pp-cli clients status - Get information about configured clients
adguard-home-pp-cli clients update - Update client information
dhcp
Built-in DHCP server controls
adguard-home-pp-cli dhcp add-static-lease - Adds a static lease
adguard-home-pp-cli dhcp check-active - Searches for an active DHCP server on the network
adguard-home-pp-cli dhcp interfaces - Gets the available interfaces
adguard-home-pp-cli dhcp remove-static-lease - Removes a static lease
adguard-home-pp-cli dhcp reset - Reset DHCP configuration
adguard-home-pp-cli dhcp reset-leases - Reset DHCP leases
adguard-home-pp-cli dhcp set-config - Updates the current DHCP server configuration
adguard-home-pp-cli dhcp status - Gets the current DHCP settings and status
adguard-home-pp-cli dhcp update-static-lease - Updates IP address, hostname of the static lease. IP version must be the same as previous.
dns-config
Manage dns config
adguard-home-pp-cli dns-config - Set general DNS parameters
dns-info
Manage dns info
adguard-home-pp-cli dns-info - Get general DNS parameters
filtering
Rule-based filtering
adguard-home-pp-cli filtering add-url - Add filter URL or an absolute file path
adguard-home-pp-cli filtering check-host - Check if host name is filtered
adguard-home-pp-cli filtering config - Set filtering parameters
adguard-home-pp-cli filtering refresh - Reload filtering rules from URLs. This might be needed if new URL was just added and you don't want to wait for automatic refresh to kick in. This API request is ratelimited, so you can call it freely as often as you like, it wont create unnecessary burden on servers that host the URL. This should work as intended, a force parameter is offered as last-resort attempt to make filter lists fresh. If you ever find yourself using force to make something work that otherwise wont, this is a bug and report it accordingly.
adguard-home-pp-cli filtering remove-url - Remove filter URL
adguard-home-pp-cli filtering set-rules - Set user-defined filter rules
adguard-home-pp-cli filtering set-url - Set URL parameters
adguard-home-pp-cli filtering status - Get filtering parameters
i18n
Application localization
adguard-home-pp-cli i18n change-language - Change current language. Argument must be an ISO 639-1 two-letter code.
adguard-home-pp-cli i18n current-language - Get currently set language. Result is ISO 639-1 two-letter code. Empty result means default language.
install
First-time install configuration handlers
adguard-home-pp-cli install check-config - Checks configuration
adguard-home-pp-cli install configure - Applies the initial configuration.
adguard-home-pp-cli install get-addresses - Gets the network interfaces information.
login
Manage login
adguard-home-pp-cli login - Perform administrator log-in
logout
Manage logout
adguard-home-pp-cli logout - Perform administrator log-out
parental
Blocking adult and explicit materials
adguard-home-pp-cli parental disable - Disable parental filtering
adguard-home-pp-cli parental enable - Enable parental filtering
adguard-home-pp-cli parental status - Get parental filtering status
protection
Manage protection
adguard-home-pp-cli protection - Set protection state and duration
querylog
Manage querylog
adguard-home-pp-cli querylog get-query-log-config - Get query log parameters
adguard-home-pp-cli querylog put-query-log-config - Set query log parameters
adguard-home-pp-cli querylog query-log - Get DNS server query log.
querylog-clear
Manage querylog clear
adguard-home-pp-cli querylog-clear - Clear query log
querylog-config
Manage querylog config
adguard-home-pp-cli querylog-config - Deprecated: Use PUT /querylog/config/update instead.
querylog-info
Manage querylog info
adguard-home-pp-cli querylog-info - Deprecated: Use GET /querylog/config instead.
NOTE: If interval was configured by editing configuration file or new
HTTP API call PUT /querylog/config/update and it's not equal to
previous allowed enum values then it will be equal to 90 days for
compatibility reasons.
rewrite
DNS rewrites
adguard-home-pp-cli rewrite add - Add a new Rewrite rule
adguard-home-pp-cli rewrite delete - Remove a Rewrite rule
adguard-home-pp-cli rewrite list - Get list of Rewrite rules
adguard-home-pp-cli rewrite settings-get - Get rewrite settings
adguard-home-pp-cli rewrite settings-update - Update rewrite settings
adguard-home-pp-cli rewrite update - Update a Rewrite rule
safebrowsing
Blocking malware/phishing sites
adguard-home-pp-cli safebrowsing disable - Disable safebrowsing
adguard-home-pp-cli safebrowsing enable - Enable safebrowsing
adguard-home-pp-cli safebrowsing status - Get safebrowsing status
safesearch
Enforce family-friendly results in search engines
adguard-home-pp-cli safesearch disable - Disable safesearch
adguard-home-pp-cli safesearch enable - Enable safesearch
adguard-home-pp-cli safesearch settings - Update safesearch settings
adguard-home-pp-cli safesearch status - Get safesearch status
stats
AdGuard Home statistics
adguard-home-pp-cli stats get-config - Get statistics parameters
adguard-home-pp-cli stats put-config - Set statistics parameters
adguard-home-pp-cli stats stats - Get DNS server statistics
stats-config
Manage stats config
adguard-home-pp-cli stats-config - Deprecated: Use PUT /stats/config/update instead.
stats-info
Manage stats info
adguard-home-pp-cli stats-info - Deprecated: Use GET /stats/config instead.
NOTE: If interval was configured by editing configuration file or new
HTTP API call PUT /stats/config/update and it's not equal to
previous allowed enum values then it will be equal to 90 days for
compatibility reasons.
stats-reset
Manage stats reset
adguard-home-pp-cli stats-reset - Reset all statistics to zeroes
status
Manage status
adguard-home-pp-cli status - Get DNS server current status and general settings
test-upstream-dns
Manage test upstream dns
adguard-home-pp-cli test-upstream-dns - Test upstream configuration
tls
AdGuard Home HTTPS/DoH/DoQ/DoT settings
adguard-home-pp-cli tls configure - Updates current TLS configuration
adguard-home-pp-cli tls status - Returns TLS configuration and its status
adguard-home-pp-cli tls validate - Checks if the current TLS configuration is valid
update
Manage update
adguard-home-pp-cli update - Begin auto-upgrade procedure
version-json
Manage version json
adguard-home-pp-cli version-json - Gets information about the latest available version of AdGuard
Output Formats
# Human-readable table (default in terminal, JSON when piped)
adguard-home-pp-cli access list
# JSON for scripting and agents
adguard-home-pp-cli access list --json
# Filter to specific fields
adguard-home-pp-cli access list --json --select id,name,status
# Dry run — show the request without sending
adguard-home-pp-cli access list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
adguard-home-pp-cli access list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
adguard-home-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/adguard-home-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
ADGUARD_HOME_USERNAME | per_call | Yes | |
ADGUARD_HOME_PASSWORD | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
adguard-home-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $ADGUARD_HOME_USERNAME
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press