HKUDS cli-anything-adguardhome
Network-wide ad blocking and DNS management via the AdGuard Home REST API. Designed for AI agents and power users who need to manage filtering, DNS rewrites, clients, DHCP, and query logs without a GUI.
Installation
This CLI is installed as part of the cli-anything-adguardhome package:
pip install cli-anything-adguardhome
Prerequisites:
- Python 3.10+
- AdGuard Home must be installed and running
- Install AdGuard Home:
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
Usage
Basic Commands
# Show help
cli-anything-adguardhome --help
# Start interactive REPL mode
cli-anything-adguardhome
# Check server status
cli-anything-adguardhome server status
# Run with JSON output (for agent consumption)
cli-anything-adguardhome --json server status
REPL Mode
When invoked without a subcommand, the CLI enters an interactive REPL session:
cli-anything-adguardhome
# Enter commands interactively with tab-completion and history
Command Groups
Config
Connection and configuration management.
| Command | Description |
|---|---|
show |
Show current connection configuration |
save |
Save connection settings to a config file |
test |
Test the connection to AdGuard Home |
Server
Server status and control commands.
| Command | Description |
|---|---|
status |
Show server protection status |
version |
Show AdGuard Home version |
restart |
Restart the AdGuard Home server |
Filter
DNS filter list management.
| Command | Description |
|---|---|
list |
List all configured filter lists |
status |
Show filtering status |
toggle |
Enable or disable filtering globally |
add |
Add a new filter list by URL |
remove |
Remove a filter list |
enable |
Enable a specific filter list |
disable |
Disable a specific filter list |
refresh |
Force-refresh all filter lists |
Blocking
Parental control, safe browsing, and safe search settings.
| Command | Description |
|---|---|
parental status |
Show parental control status |
parental enable |
Enable parental control |
parental disable |
Disable parental control |
safebrowsing status |
Show safe browsing status |
safebrowsing enable |
Enable safe browsing |
safebrowsing disable |
Disable safe browsing |
safesearch status |
Show safe search status |
safesearch enable |
Enable safe search |
safesearch disable |
Disable safe search |
Blocked-Services
Manage blocked internet services.
| Command | Description |
|---|---|
list |
List currently blocked services |
set |
Set the list of blocked services |
Clients
Client device management.
| Command | Description |
|---|---|
list |
List all configured clients |
add |
Add a new client by name and IP |
remove |
Remove a client |
show |
Show details for a specific client |
Stats
Query statistics.
| Command | Description |
|---|---|
show |
Show DNS query statistics |
reset |
Reset all statistics |
config |
View or update statistics retention interval |
Log
DNS query log management.
| Command | Description |
|---|---|
show |
Show recent DNS query log entries |
config |
View or update query log settings |
clear |
Clear the query log |
Rewrite
DNS rewrite rules.
| Command | Description |
|---|---|
list |
List all DNS rewrite rules |
add |
Add a DNS rewrite rule |
remove |
Remove a DNS rewrite rule |
DHCP
DHCP server management.
| Command | Description |
|---|---|
status |
Show DHCP server status |
leases |
List active DHCP leases |
add-static |
Add a static DHCP lease |
remove-static |
Remove a static DHCP lease |
TLS
TLS/HTTPS configuration.
| Command | Description |
|---|---|
status |
Show TLS configuration status |
Examples
Check Server Status
cli-anything-adguardhome server status
cli-anything-adguardhome server version
Manage Filter Lists
# List current filters
cli-anything-adguardhome filter list
# Add a new blocklist
cli-anything-adguardhome filter add --url https://somehost.com/list.txt --name "My List"
# Refresh all filters
cli-anything-adguardhome filter refresh
DNS Rewrites
# Add a local DNS entry
cli-anything-adguardhome rewrite add --domain "myserver.local" --answer "192.168.1.50"
# List all rewrites
cli-anything-adguardhome rewrite list
Client Management
cli-anything-adguardhome clients add --name "My PC" --ip 192.168.1.100
cli-anything-adguardhome clients list
Query Statistics
# Show stats (human-readable)
cli-anything-adguardhome stats show
# Show stats (JSON for agents)
cli-anything-adguardhome --json stats show
Output Formats
All commands support dual output modes:
- Human-readable (default): Tables, colors, formatted text
- Machine-readable (
--jsonflag): Structured JSON for agent consumption
# Human output
cli-anything-adguardhome filter list
# JSON output for agents
cli-anything-adguardhome --json filter list
For AI Agents
When using this CLI programmatically:
- Always use
--jsonflag for parseable output - Check return codes - 0 for success, non-zero for errors
- Parse stderr for error messages on failure
- Use absolute paths for all file operations
- Test connection first with
config testbefore other commands
More Information
- Full documentation: See README.md in the package
- Test coverage: See TEST.md in the package
- Methodology: See HARNESS.md in the cli-anything-plugin
Version
1.0.0