The missing command-line interface for AdGuard Home.
Manage your AdGuard Home instance from the terminal: clients, blocked services, DNS rewrites, query logs, filters, DHCP, TLS, and more. Full API coverage with structured output.
AdGuard Home has a web UI and a REST API, but no official CLI. The only existing CLI (adctl) covers ~20% of the API. This project covers 90%+ of AdGuard Home's 81 API operations.
Built for homelab operators, sysadmins, and anyone who automates their DNS infrastructure.
go install github.com/jjuanrivvera/adguard-cli/cmd/adguard-home@latestDownload the latest release from the Releases page.
# Configure your instance
adguard-home setup
# Check connectivity
adguard-home doctor
# View server status
adguard-home status
# List configured clients
adguard-home clients list
# Check DNS stats
adguard-home statsOr use environment variables for CI/automation:
export ADGUARD_URL="http://192.168.0.105:8001"
export ADGUARD_USERNAME="admin"
export ADGUARD_PASSWORD="your-password"
adguard-home clients list -o json | jq '.[].name'| Command | Description |
|---|---|
status |
Server status, enable/disable protection |
stats |
DNS query statistics, reset |
clients |
List, find, add, delete clients |
services |
List, block, unblock services globally |
rewrites |
List, add, delete DNS rewrites |
log |
View DNS query log |
filters |
List, add, remove, refresh filter lists |
dhcp |
DHCP status, leases, static lease management |
tls |
TLS/HTTPS configuration status |
dns |
DNS config, cache clear, host blocking check |
safebrowsing |
Enable/disable safe browsing |
parental |
Enable/disable parental control |
safesearch |
Safe search enforcement per engine |
access |
Allowed/disallowed clients and blocked hosts |
check-update |
Check for AdGuard Home updates |
update |
Trigger AdGuard Home update |
doctor |
Run diagnostic checks |
setup |
Interactive configuration wizard |
All read commands support --output / -o:
# Table (default)
adguard-home clients list
# JSON (for scripting)
adguard-home clients list -o json
# YAML
adguard-home stats -o yaml# List all clients with their IDs and blocked services
adguard-home clients list
# Find which client owns an IP
adguard-home clients find 192.168.0.57
# Add a new client
adguard-home clients add "Smart TV" "192.168.0.110,192.168.0.71"
# Delete a client
adguard-home clients delete "Smart TV"# See what's blocked globally
adguard-home services blocked
# Block TikTok and Instagram
adguard-home services block tiktok,instagram
# Unblock YouTube
adguard-home services unblock youtube# List all rewrites
adguard-home rewrites list
# Add a local DNS entry
adguard-home rewrites add homelab.local 192.168.0.100
# Remove a rewrite
adguard-home rewrites delete homelab.local 192.168.0.100# Check if a domain is blocked
adguard-home dns check youtube.com
# View recent query log
adguard-home log -n 50
# Clear DNS cache
adguard-home dns cache-clear# List all filter lists with rule counts
adguard-home filters list
# Add a new filter list
adguard-home filters add "OISD Big" "https://big.oisd.nl"
# Refresh all filters
adguard-home filters refresh# Show DHCP status and lease count
adguard-home dhcp status
# List all leases
adguard-home dhcp leases
# Add a static lease
adguard-home dhcp add-lease "AA:BB:CC:DD:EE:FF" "192.168.0.50" "my-server"Config lives at ~/.adguard-cli/config.yaml:
instances:
default:
url: http://192.168.0.105:8001
username: admin
secondary:
url: http://10.0.0.1:3000
username: admin
current_instance: default
output:
format: table
color: autoPasswords are stored in your system keyring (macOS Keychain, GNOME Keyring, KWallet) or in an AES-256-GCM encrypted file as fallback on headless servers. They are never stored in the config YAML.
Switch instances: adguard-home --instance secondary clients list
| Variable | Description |
|---|---|
ADGUARD_URL |
AdGuard Home base URL |
ADGUARD_USERNAME |
HTTP Basic auth username |
ADGUARD_PASSWORD |
HTTP Basic auth password |
Environment variables override the config file.
| Category | Operations | Covered |
|---|---|---|
| Status/Global | status, protection toggle, DNS config, cache clear | Yes |
| Clients | list, find, add, update, delete | Yes |
| Blocked Services | list all, list blocked, get, set | Yes |
| DNS Rewrites | list, add, delete | Yes |
| Query Log | query, clear | Yes |
| Filtering | status, add, remove, refresh, check host | Yes |
| DHCP | status, interfaces, leases, static lease CRUD, reset | Yes |
| TLS | status, configure | Yes |
| Safe Browsing | status, enable, disable | Yes |
| Parental | status, enable, disable | Yes |
| Safe Search | status per engine | Yes |
| Access Control | list allowed/disallowed/blocked | Yes |
| Version | check update, trigger update | Yes |
| Stats | get, reset | Yes |
git clone https://github.com/jjuanrivvera/adguard-cli.git
cd adguard-cli
go build -o adguard-home ./cmd/adguard-home/Cross-compile:
# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o adguard-home-darwin-arm64 ./cmd/adguard-home/
# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o adguard-home-linux-amd64 ./cmd/adguard-home/
# Windows
GOOS=windows GOARCH=amd64 go build -o adguard-home.exe ./cmd/adguard-home/MIT