README
¶
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.
Why
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.
Install
Install script (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/jjuanrivvera/adguard-cli/main/install.sh | sh
Homebrew (macOS / Linux)
brew install jjuanrivvera/adguard-cli/adguard-cli
Scoop (Windows)
scoop install https://raw.githubusercontent.com/jjuanrivvera/scoop-adguard-cli/main/adguard-cli.json
Go
go install github.com/jjuanrivvera/adguard-cli/cmd/adguard-home@latest
Binary
Download the latest release from the Releases page (deb/rpm/apk and archives for Linux, macOS, and Windows).
Quick Start
# 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 stats
Or 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'
Commands
| 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 |
server check-update |
Check for AdGuard Home server updates |
server upgrade |
Update the AdGuard Home server |
update |
Update the adguard-home CLI itself |
doctor |
Run diagnostic checks |
setup |
Interactive wizard: add an instance (URL, user, password) |
config |
List, switch, view, and remove configured instances |
Output Formats
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
Examples
Client Management
# 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"
Blocked Services
# 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
DNS Rewrites
# 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
DNS Diagnostics
# 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
Filter Lists
# 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
DHCP
# 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"
Configuration
Add an instance with the interactive wizard — it prompts for the URL, username, password, and an instance name:
adguard-home setup
adguard-cli is multi-instance: configure as many AdGuard Home servers as you want (home, office, a client's box) and switch between them. Manage them with config:
adguard-home config list # list instances (the active one is marked with *)
adguard-home config view # details: name, URL, username, active
adguard-home config use office # switch the active instance
adguard-home config remove office # delete an instance and its stored password
adguard-home config path # print the config file location
To run a single command against a non-active instance without switching, use --instance (or its --profile alias):
adguard-home --instance office clients list
Config lives at ~/.adguard-cli/config.yaml, managed by setup and config (you rarely edit it by hand):
instances:
home:
url: http://192.168.0.105:8001
username: admin
office:
url: http://10.0.0.1:3000
username: admin
current_instance: home
output:
format: table
color: auto
Passwords are never stored in the YAML — they live in your system keyring (macOS Keychain, GNOME Keyring, KWallet), with an AES-256-GCM encrypted file as fallback on headless servers.
Environment Variables
| 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.
API Coverage
| 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 |
Building from Source
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/
License
MIT
Directories