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 (--json flag): 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:

1. Always use --json flag for parseable output
2. Check return codes - 0 for success, non-zero for errors
3. Parse stderr for error messages on failure
4. Use absolute paths for all file operations
5. Test connection first with config test before 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