pihole-ctl
Manage and monitor local Pi-hole instance. Query FTL database for statistics (blocked ads, top clients) and control service via CLI. Use when user asks "how many ads blocked", "pihole status", or "update gravity".
About this skill
The Pi-hole Controller skill provides comprehensive tools for AI agents to interact with a local Pi-hole ad-blocking solution. It empowers agents to query the Pi-hole FTL database for detailed statistics, such as the number of blocked advertisements, top querying clients, and frequently blocked domains. Beyond monitoring, it also allows for direct management of the Pi-hole service through its command-line interface, enabling actions like enabling or disabling ad-blocking and updating blocklists (Gravity). This skill is invaluable for users who rely on Pi-hole for network-wide ad blocking and desire automated insights or rapid control. An AI agent equipped with this skill can quickly answer queries about network activity, perform routine maintenance tasks, or diagnose potential issues without manual intervention. It streamlines the process of managing a critical network service by providing an intelligent interface. By integrating this skill, users gain a conversational and automated way to interact with their Pi-hole setup. Instead of logging into the web interface or manually executing CLI commands, an AI agent can interpret natural language requests and execute the appropriate actions or data retrievals. This enhances convenience, saves time, and makes Pi-hole management more accessible, especially for users who prefer an AI-driven workflow for their smart home or local network infrastructure.
Best use case
The primary use case for `pihole-ctl` is to provide an AI agent with the capability to monitor and manage a local Pi-hole instance through natural language commands. Home users, small office administrators, and tech enthusiasts who use Pi-hole for network-wide ad-blocking and DNS management will benefit most by gaining an automated and conversational interface to check statistics, control services, and update blocklists without manual CLI interaction or web UI access.
Manage and monitor local Pi-hole instance. Query FTL database for statistics (blocked ads, top clients) and control service via CLI. Use when user asks "how many ads blocked", "pihole status", or "update gravity".
Users should expect to receive up-to-date Pi-hole statistics in JSON format or confirmation of executed CLI commands (e.g., Pi-hole service status, Gravity update success).
Practical example
Example input
How many ads has Pi-hole blocked in the last 24 hours?
Example output
{"ads_blocked_today": 12345, "dns_queries_today": 56789, "ads_percentage_blocked": 21.7}When to use this skill
- When you need to check Pi-hole's ad-blocking status or query statistics.
- To quickly enable or disable ad-blocking on your network.
- For automating the update of your Pi-hole's blocklists (Gravity).
- To identify which devices are making the most DNS queries or being blocked.
When not to use this skill
- If you don't have a Pi-hole instance running on your network.
- When direct access to the Pi-hole web interface or SSH is preferred for complex configurations.
- If the AI agent lacks the necessary permissions (read access to DB, sudo for CLI).
- For remote Pi-hole instances not accessible from the agent's host.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/pihole-ctl/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How pihole-ctl Compares
| Feature / Agent | pihole-ctl | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | medium | N/A |
Frequently Asked Questions
What does this skill do?
Manage and monitor local Pi-hole instance. Query FTL database for statistics (blocked ads, top clients) and control service via CLI. Use when user asks "how many ads blocked", "pihole status", or "update gravity".
How difficult is it to install?
The installation complexity is rated as medium. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Top AI Agents for Productivity
See the top AI agent skills for productivity, workflow automation, operational systems, documentation, and everyday task execution.
AI Agents for Freelancers
Browse AI agent skills for freelancers handling client research, proposals, outreach, delivery systems, documentation, and repeatable admin work.
Best AI Skills for ChatGPT
Find the best AI skills to adapt into ChatGPT workflows for research, writing, summarization, planning, and repeatable assistant tasks.
SKILL.md Source
# Pi-hole Controller ## Usage - **Role**: Network Guardian. - **Trigger**: "Check Pi-hole", "Adblock status", "Who is querying top domains?". - **Output**: JSON stats or CLI command results. ## Capabilities 1. **Statistics**: Query FTL database for accurate logs (Last 24h, Top Domains). 2. **Management**: Enable/Disable blocking (`pihole enable/disable`). 3. **Blocklists**: Update Gravity (`pihole -g`). 4. **Audit**: Identify chatty clients or top blocked domains. ## Scripts - `scripts/query_db.py`: Python script using native `sqlite3` library to query Pi-hole stats safely. - Requires read permission on `/etc/pihole/pihole-FTL.db`. - Usage: `python3 scripts/query_db.py --summary --hours 24` - Usage: `python3 scripts/query_db.py --top 10` ## Permissions - **Database Access**: The user running this skill must have read access to `/etc/pihole/pihole-FTL.db`. - Recommended: Add user to `pihole` group (`usermod -aG pihole ubuntu`). - **Management Commands**: `pihole` CLI commands (enable/disable) require `sudo` or must be run by a user with appropriate permissions. ## Reference Materials - [Database Schema](references/db-schema.md)
Related Skills
find-skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
filesystem
Advanced filesystem operations for listing files, searching content, batch processing, and directory analysis. Supports recursive search, file type filtering, size analysis, and batch operations like copy/move/delete. Use when you need to: list directory contents, search for files by name or content, analyze directory structures, perform batch file operations, or analyze file sizes and distribution.
Budget & Expense Tracker — AI Agent Financial Command Center
Track every dollar, enforce budgets, spot spending patterns, and build wealth — all through natural conversation with your AI agent.
yt-dlp
A robust CLI wrapper for yt-dlp to download videos, playlists, and audio from YouTube and thousands of other sites. Supports format selection, quality control, metadata embedding, and cookie authentication.
time-checker
Check accurate current time, date, and timezone information for any location worldwide using time.is. Use when the user asks "what time is it in X", "current time in Y", or needs to verify timezone offsets.
mermaid-architect
Generate beautiful, hand-drawn Mermaid diagrams with robust syntax (quoted labels, ELK layout). Use this skill when the user asks for "diagram", "flowchart", "sequence diagram", or "visualize this process".
memory-cache
High-performance temporary storage system using Redis. Supports namespaced keys (mema:*), TTL management, and session context caching. Use for: (1) Saving agent state, (2) Caching API results, (3) Sharing data between sub-agents.
mema
Mema's personal brain - SQLite metadata index for documents and Redis short-term context buffer. Use for organizing workspace knowledge paths and managing ephemeral session state.
file-organizer-skill
Organize files in directories by grouping them into folders based on their extensions or date. Includes Dry-Run, Recursive, and Undo capabilities.
media-compress
Compress and convert images and videos using ffmpeg. Use when the user wants to reduce file size, change format, resize, or optimize media files. Handles common formats like JPG, PNG, WebP, MP4, MOV, WebM. Triggers on phrases like "compress image", "compress video", "reduce file size", "convert to webp/mp4", "resize image", "make image smaller", "batch compress", "optimize media".
edge-tts
Text-to-speech conversion using node-edge-tts npm package for generating audio from text. Supports multiple voices, languages, speed adjustment, pitch control, and subtitle generation. Use when: (1) User requests audio/voice output with the "tts" trigger or keyword. (2) Content needs to be spoken rather than read (multitasking, accessibility, driving, cooking). (3) User wants a specific voice, speed, pitch, or format for TTS output.
ocr-local
Extract text from images using Tesseract.js OCR (100% local, no API key required). Supports Chinese (simplified/traditional) and English.