cli-anything-adguardhome 是做什麼的？
透過 AdGuard Home REST API 實現網路層級的廣告封鎖與 DNS 管理。專為 AI 代理與進階用戶設計，無須圖形介面即可管理過濾、DNS 重寫、用戶端、DHCP 與查詢日誌。
安裝
此 CLI 作為 cli-anything-adguardhome 套件的一部分安裝：
pip install cli-anything-adguardhome
先決條件：
- Python 3.10+
- 必須安裝並執行 AdGuard Home
- 安裝 AdGuard Home：
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
使用方式
基本指令
# 顯示說明
cli-anything-adguardhome --help
# 啟動互動式 REPL 模式
cli-anything-adguardhome
# 檢查伺服器狀態
cli-anything-adguardhome server status
# 以 JSON 輸出執行（供代理程式使用）
cli-anything-adguardhome --json server status
REPL 模式
在不指定子指令的情況下呼叫時，CLI 會進入互動式 REPL 工作階段：
cli-anything-adguardhome
# 以 Tab 補全與歷史記錄功能互動式輸入指令
指令群組
Config（設定）
連線與組態管理。
| 指令 | 說明 |
|---|---|
show | 顯示目前連線組態 |
save | 將連線設定儲存至設定檔 |
test | 測試與 AdGuard Home 的連線 |
Server（伺服器）
伺服器狀態與控制指令。
| 指令 | 說明 |
|---|---|
status | 顯示伺服器保護狀態 |
version | 顯示 AdGuard Home 版本 |
restart | 重新啟動 AdGuard Home 伺服器 |
Filter（過濾器）
DNS 過濾清單管理。
| 指令 | 說明 |
|---|---|
list | 列出所有已設定過濾清單 |
status | 顯示過濾狀態 |
toggle | 全域啟用或停用過濾 |
add | 透過 URL 新增過濾清單 |
remove | 移除過濾清單 |
enable | 啟用特定過濾清單 |
disable | 停用特定過濾清單 |
refresh | 強制重新整理所有過濾清單 |
Blocking（封鎖）
家長監護、安全瀏覽與安全搜尋設定。
| 指令 | 說明 |
|---|---|
parental status | 顯示家長監護狀態 |
parental enable | 啟用家長監護 |
parental disable | 停用家長監護 |
safebrowsing status | 顯示安全瀏覽狀態 |
safebrowsing enable | 啟用安全瀏覽 |
safebrowsing disable | 停用安全瀏覽 |
safesearch status | 顯示安全搜尋狀態 |
safesearch enable | 啟用安全搜尋 |
safesearch disable | 停用安全搜尋 |
Blocked-Services（被封鎖服務）
管理被封鎖的網際網路服務。
| 指令 | 說明 |
|---|---|
list | 列出目前已封鎖的服務 |
set | 設定被封鎖的服務清單 |
Clients（用戶端）
用戶端設備管理。
| 指令 | 說明 |
|---|---|
list | 列出所有已設定的用戶端 |
add | 依名稱與 IP 新增用戶端 |
remove | 移除用戶端 |
show | 顯示特定用戶端的詳細資訊 |
Stats（統計）
查詢統計資料。
| 指令 | 說明 |
|---|---|
show | 顯示 DNS 查詢統計資料 |
reset | 重設所有統計資料 |
config | 檢視或更新統計資料保留間隔 |
Log（日誌）
DNS 查詢日誌管理。
| 指令 | 說明 |
|---|---|
show | 顯示最近的 DNS 查詢日誌項目 |
config | 檢視或更新查詢日誌設定 |
clear | 清除查詢日誌 |
Rewrite（重寫）
DNS 重寫規則。
| 指令 | 說明 |
|---|---|
list | 列出所有 DNS 重寫規則 |
add | 新增 DNS 重寫規則 |
remove | 移除 DNS 重寫規則 |
DHCP
DHCP 伺服器管理。
| 指令 | 說明 |
|---|---|
status | 顯示 DHCP 伺服器狀態 |
leases | 列出作用中的 DHCP 租約 |
add-static | 新增靜態 DHCP 租約 |
remove-static | 移除靜態 DHCP 租約 |
TLS
TLS/HTTPS 組態。
| 指令 | 說明 |
|---|---|
status | 顯示 TLS 組態狀態 |
範例
檢查伺服器狀態
cli-anything-adguardhome server status
cli-anything-adguardhome server version
管理過濾清單
# 列出目前過濾器
cli-anything-adguardhome filter list
# 新增封鎖清單
cli-anything-adguardhome filter add --url https://somehost.com/list.txt --name "我的清單"
# 重新整理所有過濾器
cli-anything-adguardhome filter refresh
DNS 重寫
# 新增本機 DNS 項目
cli-anything-adguardhome rewrite add --domain "myserver.local" --answer "192.168.1.50"
# 列出所有重寫規則
cli-anything-adguardhome rewrite list
用戶端管理
cli-anything-adguardhome clients add --name "我的電腦" --ip 192.168.1.100
cli-anything-adguardhome clients list
查詢統計
# 顯示統計（人類可讀）
cli-anything-adguardhome stats show
# 顯示統計（JSON 格式，供代理程式使用）
cli-anything-adguardhome --json stats show
輸出格式
所有指令都支援雙重輸出模式：
- 人類可讀（預設）：表格、色彩、格式化文字
- 機器可讀（
--json旗標）：結構化 JSON，供代理程式使用
# 人類輸出
cli-anything-adguardhome filter list
# 供代理程式使用的 JSON 輸出
cli-anything-adguardhome --json filter list
給 AI 代理程式的建議
以程式方式使用此 CLI 時：
- 一律使用
--json旗標，以取得可解析的輸出 - 檢查回傳碼 — 0 代表成功，非零代表錯誤
- 解析 stderr，以取得失敗時的錯誤訊息
- 在所有檔案操作中使用絕對路徑
- 先以
config test測試連線，再執行其他指令
更多資訊
- 完整文件：請參閱套件內的 README.md
- 測試涵蓋範圍：請參閱套件內的 TEST.md
- 方法論：請參閱 cli-anything-plugin 中的 HARNESS.md
版本
1.0.0