Guide · Agent skill

How to use the AdGuard Home CLI agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

This guide explains how to install and use the cli-anything-adguardhome skill, which lets an AI agent manage a self-hosted AdGuard Home network ad-blocker through a command-line tool instead of its web interface. It is written for readers who have not used agent skills before. By the end you will know what the skill does, how to install it, how to ask an agent for common changes, and which safety points to check first.

AdGuard Home CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill

Quick start

1Install AdGuard Home. Make sure AdGuard Home is installed and running on your network, and that you have its REST API connection details.
2Install the Python package. Run pip install cli-anything-adguardhome on a machine with Python 3.10 or newer.
3Add the skill files. Download the ZIP from the AdGuard Home skill page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
4Test the connection. Run cli-anything-adguardhome config test to confirm the tool can reach your AdGuard Home server.
5Check server status. Run cli-anything-adguardhome server status to confirm protection is running.
6Make a request in plain language. Ask the agent for a change, such as adding a blocklist or a DNS rewrite, with exact names, URLs or IP addresses.
7Review risky changes. Check any restart, filter removal, log clearing or DHCP request before the agent runs it, since the skill has no confirmation step.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to use a tool. This skill teaches the agent to control AdGuard Home, a network-wide ad blocker and DNS server, through the cli-anything-adguardhome command-line tool.

Once installed, the agent can check server status, add or toggle blocklists, add local DNS rewrites, manage client devices and DHCP leases, and read or clear the query log. The tool can print results as JSON, which the agent can parse.

What you need before you install

The skill only wraps an existing AdGuard Home server. It cannot block ads on its own. The source lists these requirements:

Python 3.10 or newer
AdGuard Home installed and running on your network
AdGuard Home REST API connection details, including the credentials needed to connect
A way for the tool to reach the AdGuard Home API over the network

Install the skill package and the skill files

Install the CLI package with pip. Then add the skill files so your agent can find them. You can download the ZIP from the AdGuard Home skill page and unzip it into one of these locations:

For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/
Project: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills (upload)

pip install cli-anything-adguardhome

Check the connection before making changes

The source recommends testing the connection first. Use the config commands to view and test your connection settings. The source does not say exactly how credentials are supplied, so check the package README before you start.

Also check that the basic commands return results. Help, server status and version are read-only checks.

Run config show to see the current connection settings
Run config test to confirm the tool can reach AdGuard Home
Run server status to confirm protection status

cli-anything-adguardhome config test

Ask the agent for natural requests

You do not need to remember command syntax. Once the skill is installed, describe the change you want in plain language and the agent will choose the matching command groups such as filter, rewrite, clients, stats, log or dhcp.

Be specific about names, domains and IP addresses. The agent is more likely to choose the right command when you give exact values.

Check whether AdGuard Home is protecting my network right now.
Add the blocklist at this URL and call it My List, then refresh all filters.
Create a local DNS entry so myserver.local points to 192.168.1.50.
Register my PC at 192.168.1.100 as a client called My PC.
Show me the top query statistics in JSON.

Run the commands yourself

You can also run the tool directly. Commands are grouped by area. Running the tool without a subcommand opens an interactive session with tab-completion and history. Add --json before a command to get machine-readable output.

Help: cli-anything-adguardhome --help
Server status: cli-anything-adguardhome server status
Filter list: cli-anything-adguardhome filter list
Add a DNS rewrite: cli-anything-adguardhome rewrite add --domain "myserver.local" --answer "192.168.1.50"
JSON output: cli-anything-adguardhome --json server status

cli-anything-adguardhome filter add --url https://somehost.com/list.txt --name "My List"
cli-anything-adguardhome filter refresh
cli-anything-adguardhome rewrite list

Safety notes: scripts, network access and risky commands

This skill runs scripts and uses the network. It needs access to your AdGuard Home API, so the agent will send requests to your server. Only install it on a machine you control and only give it access to a network you manage.

Some commands can disrupt connectivity for every device on your network. The skill gives no confirmation step, so the agent may run them right away. Review requests before the agent acts, especially for restart, filter removal, log clearing, and DHCP changes. Do not paste admin credentials into a chat with an agent.

Restart can interrupt DNS for all devices.
Removing filters or clearing the query log cannot be undone from the tool.
DHCP changes can affect how devices get addresses.
Keep credentials out of chat; configure them through the tool's own connection settings.

Tips for getting reliable results

The source gives a few rules for programmatic use. Following them makes the agent's output easier to check and parse.

Always use the --json flag when the agent reads output.
Check return codes: 0 means success, non-zero means an error.
When a command fails, read stderr for the error message.
Use absolute paths for any file operations.
Run config test before other commands on a new setup.
Full command reference is in README.md, and test coverage is in TEST.md, both in the package.

What people use it for

Check whether AdGuard Home protection is on and which version is running.
Add a blocklist by URL and refresh all filter lists.
Create a local DNS rewrite so a home server name resolves to a LAN IP.
Register known devices as clients by name and IP address.
Read query statistics or recent query log entries in JSON for an agent workflow.

Frequently asked questions

Is the AdGuard Home CLI agent skill free?

The source is published under the Apache-2.0 licence, and the skill is distributed as part of the HKUDS/CLI-Anything project. The source does not mention pricing, so check the repository for any licence details. AdGuard Home itself must already be installed and running.

What do I need to install the AdGuard Home skill?

You need Python 3.10 or newer, the pip package cli-anything-adguardhome, and a running AdGuard Home instance with its REST API connection details. The skill does not install AdGuard Home for you, so the source's install command for AdGuard Home is a separate step.

Where do I put the skill files for Claude?

Unzip the downloaded ZIP into ~/.claude/skills/ for a personal setup, or into .claude/skills/ inside a project folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Can this skill block ads without AdGuard Home?

No. The skill only wraps an existing AdGuard Home server through its REST API. Ad blocking is done by AdGuard Home itself.

Why won't the connection test work?

The source says to run config test first, but it does not describe how credentials are supplied or troubleshoot errors. Check that AdGuard Home is running, that the API is reachable from your machine, and read the package README for connection setup. When a command fails, read stderr for the error message.

How does this compare with using the AdGuard Home web interface?

The skill is aimed at people who want scripted or agent-driven changes without a GUI. It offers JSON output that an agent can parse. The web interface remains the visual option. The source does not compare the two in detail.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits home-lab users and network administrators who already run AdGuard Home and want an AI agent or scripts to handle routine filter, rewrite, client and log tasks. It is a poor fit for anyone without an AdGuard Home server, or for anyone who wants changes made to a production network without review, because the skill runs scripts, uses the network and has no confirmation step.

Download the skill