# 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".

- Skill: `1999azzar/pihole-ctl` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 1999azzar/pihole-ctl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/1999azzar/pihole-ctl/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 1999AZZAR (https://skillmd.com/u/1999azzar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/1999azzar/pihole-ctl

---


# 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.

## Safety & Approval Gates
The following actions affect the entire local network and **require explicit human confirmation** before execution:

| Action | Risk | Gate |
| --- | --- | --- |
| `pihole disable` | ⚠️ HIGH — Disables DNS blocking network-wide | **Requires human approval** |
| `pihole -g` (gravity update) | MEDIUM — Temporarily disrupts DNS resolution | **Requires human approval** |
| Database queries (read-only) | LOW | No gate required |
| `pihole status` / `pihole enable` | LOW | No gate required |

> **Note**: The agent MUST NOT disable Pi-hole without explicit user confirmation, as this removes DNS-level protection for all devices on the network.

## 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)