adguard-home-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. adguard_home_cli-0.1.0/PKG-INFO +204 -0
  2. adguard_home_cli-0.1.0/README.md +176 -0
  3. adguard_home_cli-0.1.0/pyproject.toml +45 -0
  4. adguard_home_cli-0.1.0/src/adguard_home_cli/__init__.py +1 -0
  5. adguard_home_cli-0.1.0/src/adguard_home_cli/cli.py +20 -0
  6. adguard_home_cli-0.1.0/src/adguard_home_cli/spec.yaml +3274 -0
adguard_home_cli-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,204 @@
1
+ Metadata-Version: 2.4
2
+ Name: adguard-home-cli
3
+ Version: 0.1.0
4
+ Summary: A full-coverage CLI for AdGuard Home, generated from its official OpenAPI spec
5
+ Project-URL: Homepage, https://github.com/shivaam/openapi-cli-gen
6
+ Project-URL: Source, https://github.com/shivaam/openapi-cli-gen/tree/main/wrappers/adguard-home-cli
7
+ Project-URL: Issues, https://github.com/shivaam/openapi-cli-gen/issues
8
+ Project-URL: Generator, https://github.com/shivaam/openapi-cli-gen
9
+ Author: Shivam Rastogi
10
+ License: MIT
11
+ Keywords: api,cli,generated,openapi,rest
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Software Development
24
+ Classifier: Topic :: Utilities
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: openapi-cli-gen>=0.0.14
27
+ Description-Content-Type: text/markdown
28
+
29
+ # adguard-home-cli
30
+
31
+ **A full-coverage CLI for [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome).** Every endpoint in the AdGuard Home OpenAPI spec, exposed as a typed shell command. Generated from [AdGuard Home's official OpenAPI spec](https://github.com/AdguardTeam/AdGuardHome/blob/master/openapi/openapi.yaml) using [openapi-cli-gen](https://github.com/shivaam/openapi-cli-gen).
32
+
33
+ ## Why
34
+
35
+ A CLI for AdGuard Home has been one of the [most-requested community features](https://github.com/AdguardTeam/AdGuardHome/issues/1147) — with [dedicated](https://github.com/AdguardTeam/AdGuardHome/issues/1428) [feature](https://github.com/AdguardTeam/AdGuardHome/issues/7917) requests asking for scripting, Infrastructure-as-Code, and automated provisioning. The project maintainers have focused on the web UI and DNS engine; there's no official CLI.
36
+
37
+ This fills the gap: every HTTP API endpoint in AdGuard Home becomes a shell command with typed flags. Useful for:
38
+
39
+ - **Ansible / homelab provisioning** — set filter URLs, block lists, TLS config from a playbook
40
+ - **Sync across instances** — dump config from one AdGuard Home, apply to another
41
+ - **Monitoring scripts** — query protection state, blocked counts, query logs
42
+ - **Scheduled blocked-services toggles** — turn Netflix on for movie night via cron
43
+ - **Bulk rule management** — add / remove user rules programmatically
44
+
45
+ ## Install
46
+
47
+ ```bash
48
+ pipx install adguard-home-cli
49
+
50
+ # Or with uv
51
+ uv tool install adguard-home-cli
52
+ ```
53
+
54
+ ## Setup
55
+
56
+ Point it at your AdGuard Home instance. **Note:** the REST API is served under `/control`:
57
+
58
+ ```bash
59
+ export ADGUARD_HOME_CLI_BASE_URL=http://your-adguard-host:3000/control
60
+ ```
61
+
62
+ ### Authentication
63
+
64
+ AdGuard Home uses HTTP Basic auth with your admin credentials:
65
+
66
+ ```bash
67
+ export ADGUARD_HOME_CLI_USERNAME=admin
68
+ export ADGUARD_HOME_CLI_PASSWORD=your-password
69
+ ```
70
+
71
+ The CLI automatically sends the `Authorization: Basic ...` header on every request.
72
+
73
+ ## Quick Start
74
+
75
+ ```bash
76
+ # Server status (version, DNS addresses, running state)
77
+ adguard-home-cli global status
78
+
79
+ # Stats summary
80
+ adguard-home-cli stats info
81
+ adguard-home-cli stats stats
82
+
83
+ # Filter status (which lists are enabled, update intervals)
84
+ adguard-home-cli filtering status
85
+
86
+ # Add a new blocklist URL
87
+ adguard-home-cli filtering add-url \
88
+ --name "OISD Full" \
89
+ --url "https://big.oisd.nl/" \
90
+ --whitelist false
91
+
92
+ # Refresh all filters
93
+ adguard-home-cli filtering refresh
94
+
95
+ # Set user-defined block rules
96
+ adguard-home-cli filtering set-rules --rules '["||example.com^", "||tracker.io^"]'
97
+
98
+ # Look up a host (debugging)
99
+ adguard-home-cli filtering check-host --name doubleclick.net
100
+
101
+ # Client management
102
+ adguard-home-cli clients status
103
+ adguard-home-cli clients find
104
+
105
+ # Safe browsing / parental controls / safe search
106
+ adguard-home-cli safebrowsing status
107
+ adguard-home-cli parental status
108
+ adguard-home-cli safesearch status
109
+
110
+ # Blocked services (one-off block of Netflix, YouTube, etc.)
111
+ adguard-home-cli blocked_services list
112
+ adguard-home-cli blocked_services set --root '{"ids": ["netflix", "tiktok"]}'
113
+
114
+ # Query log
115
+ adguard-home-cli log query --limit 50
116
+
117
+ # DNS rewrites (local DNS entries)
118
+ adguard-home-cli rewrite list
119
+ adguard-home-cli rewrite add --domain home.lan --answer 192.168.1.10
120
+ ```
121
+
122
+ ## Discover All Commands
123
+
124
+ ```bash
125
+ # Top-level groups
126
+ adguard-home-cli --help
127
+
128
+ # Commands in a group
129
+ adguard-home-cli filtering --help
130
+
131
+ # Flags for a specific command
132
+ adguard-home-cli filtering add-url --help
133
+ ```
134
+
135
+ ## Output Formats
136
+
137
+ Every command accepts `--output-format`:
138
+
139
+ ```bash
140
+ adguard-home-cli global status --output-format table
141
+ adguard-home-cli stats info --output-format yaml
142
+ adguard-home-cli filtering status --output-format raw
143
+ ```
144
+
145
+ ## Command Groups
146
+
147
+ | Group | What it covers |
148
+ |---|---|
149
+ | `global` | Server status, DNS config, protection toggle, profile, updates |
150
+ | `install` | Initial setup wizard (address discovery, configure, check-config) |
151
+ | `filtering` | Block lists, allow lists, user rules, host lookup |
152
+ | `clients` | Per-client access lists and settings |
153
+ | `dhcp` | DHCP server + static leases |
154
+ | `log` | Query log config + search |
155
+ | `stats` | Query statistics + config |
156
+ | `blocked_services` | Time-scheduled service blocking (Netflix, TikTok, etc.) |
157
+ | `safebrowsing` | Google Safe Browsing toggle |
158
+ | `parental` | Parental control toggle |
159
+ | `safesearch` | Safe search enforcement |
160
+ | `rewrite` | Local DNS rewrites (map domains to IPs) |
161
+ | `tls` | HTTPS / DNS-over-TLS / DNS-over-HTTPS config |
162
+ | `mobileconfig` | Generate iOS/macOS mobile config profiles |
163
+ | `i18n` | UI language |
164
+
165
+ ## Real Example: Bootstrap a New AdGuard Home Instance
166
+
167
+ ```bash
168
+ #!/usr/bin/env bash
169
+ set -e
170
+
171
+ export ADGUARD_HOME_CLI_BASE_URL=http://new-adguard:3000/control
172
+ export ADGUARD_HOME_CLI_USERNAME=admin
173
+ export ADGUARD_HOME_CLI_PASSWORD=$ADMIN_PASSWORD
174
+
175
+ # Add block lists
176
+ adguard-home-cli filtering add-url --name "OISD" --url "https://big.oisd.nl/" --whitelist false
177
+ adguard-home-cli filtering add-url --name "StevenBlack" --url "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts" --whitelist false
178
+
179
+ # Refresh
180
+ adguard-home-cli filtering refresh
181
+
182
+ # Add local rewrites
183
+ adguard-home-cli rewrite add --domain router.lan --answer 192.168.1.1
184
+ adguard-home-cli rewrite add --domain nas.lan --answer 192.168.1.20
185
+
186
+ # Enable safe browsing + parental
187
+ adguard-home-cli safebrowsing enable
188
+ adguard-home-cli parental enable
189
+
190
+ # Verify
191
+ adguard-home-cli global status --output-format json | jq .protection_enabled
192
+ ```
193
+
194
+ ## How It Works
195
+
196
+ This package is a thin wrapper:
197
+ - Embeds the AdGuard Home OpenAPI spec (`spec.yaml`)
198
+ - Delegates CLI generation to [openapi-cli-gen](https://github.com/shivaam/openapi-cli-gen) at runtime
199
+
200
+ Since it's spec-driven, new AdGuard Home endpoints show up automatically on regeneration — no manual wrapping.
201
+
202
+ ## License
203
+
204
+ MIT. Not affiliated with AdGuard — this is an unofficial community CLI built on top of their public OpenAPI spec.
adguard_home_cli-0.1.0/README.md ADDED
@@ -0,0 +1,176 @@
1
+ # adguard-home-cli
2
+
3
+ **A full-coverage CLI for [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome).** Every endpoint in the AdGuard Home OpenAPI spec, exposed as a typed shell command. Generated from [AdGuard Home's official OpenAPI spec](https://github.com/AdguardTeam/AdGuardHome/blob/master/openapi/openapi.yaml) using [openapi-cli-gen](https://github.com/shivaam/openapi-cli-gen).
4
+
5
+ ## Why
6
+
7
+ A CLI for AdGuard Home has been one of the [most-requested community features](https://github.com/AdguardTeam/AdGuardHome/issues/1147) — with [dedicated](https://github.com/AdguardTeam/AdGuardHome/issues/1428) [feature](https://github.com/AdguardTeam/AdGuardHome/issues/7917) requests asking for scripting, Infrastructure-as-Code, and automated provisioning. The project maintainers have focused on the web UI and DNS engine; there's no official CLI.
8
+
9
+ This fills the gap: every HTTP API endpoint in AdGuard Home becomes a shell command with typed flags. Useful for:
10
+
11
+ - **Ansible / homelab provisioning** — set filter URLs, block lists, TLS config from a playbook
12
+ - **Sync across instances** — dump config from one AdGuard Home, apply to another
13
+ - **Monitoring scripts** — query protection state, blocked counts, query logs
14
+ - **Scheduled blocked-services toggles** — turn Netflix on for movie night via cron
15
+ - **Bulk rule management** — add / remove user rules programmatically
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ pipx install adguard-home-cli
21
+
22
+ # Or with uv
23
+ uv tool install adguard-home-cli
24
+ ```
25
+
26
+ ## Setup
27
+
28
+ Point it at your AdGuard Home instance. **Note:** the REST API is served under `/control`:
29
+
30
+ ```bash
31
+ export ADGUARD_HOME_CLI_BASE_URL=http://your-adguard-host:3000/control
32
+ ```
33
+
34
+ ### Authentication
35
+
36
+ AdGuard Home uses HTTP Basic auth with your admin credentials:
37
+
38
+ ```bash
39
+ export ADGUARD_HOME_CLI_USERNAME=admin
40
+ export ADGUARD_HOME_CLI_PASSWORD=your-password
41
+ ```
42
+
43
+ The CLI automatically sends the `Authorization: Basic ...` header on every request.
44
+
45
+ ## Quick Start
46
+
47
+ ```bash
48
+ # Server status (version, DNS addresses, running state)
49
+ adguard-home-cli global status
50
+
51
+ # Stats summary
52
+ adguard-home-cli stats info
53
+ adguard-home-cli stats stats
54
+
55
+ # Filter status (which lists are enabled, update intervals)
56
+ adguard-home-cli filtering status
57
+
58
+ # Add a new blocklist URL
59
+ adguard-home-cli filtering add-url \
60
+ --name "OISD Full" \
61
+ --url "https://big.oisd.nl/" \
62
+ --whitelist false
63
+
64
+ # Refresh all filters
65
+ adguard-home-cli filtering refresh
66
+
67
+ # Set user-defined block rules
68
+ adguard-home-cli filtering set-rules --rules '["||example.com^", "||tracker.io^"]'
69
+
70
+ # Look up a host (debugging)
71
+ adguard-home-cli filtering check-host --name doubleclick.net
72
+
73
+ # Client management
74
+ adguard-home-cli clients status
75
+ adguard-home-cli clients find
76
+
77
+ # Safe browsing / parental controls / safe search
78
+ adguard-home-cli safebrowsing status
79
+ adguard-home-cli parental status
80
+ adguard-home-cli safesearch status
81
+
82
+ # Blocked services (one-off block of Netflix, YouTube, etc.)
83
+ adguard-home-cli blocked_services list
84
+ adguard-home-cli blocked_services set --root '{"ids": ["netflix", "tiktok"]}'
85
+
86
+ # Query log
87
+ adguard-home-cli log query --limit 50
88
+
89
+ # DNS rewrites (local DNS entries)
90
+ adguard-home-cli rewrite list
91
+ adguard-home-cli rewrite add --domain home.lan --answer 192.168.1.10
92
+ ```
93
+
94
+ ## Discover All Commands
95
+
96
+ ```bash
97
+ # Top-level groups
98
+ adguard-home-cli --help
99
+
100
+ # Commands in a group
101
+ adguard-home-cli filtering --help
102
+
103
+ # Flags for a specific command
104
+ adguard-home-cli filtering add-url --help
105
+ ```
106
+
107
+ ## Output Formats
108
+
109
+ Every command accepts `--output-format`:
110
+
111
+ ```bash
112
+ adguard-home-cli global status --output-format table
113
+ adguard-home-cli stats info --output-format yaml
114
+ adguard-home-cli filtering status --output-format raw
115
+ ```
116
+
117
+ ## Command Groups
118
+
119
+ | Group | What it covers |
120
+ |---|---|
121
+ | `global` | Server status, DNS config, protection toggle, profile, updates |
122
+ | `install` | Initial setup wizard (address discovery, configure, check-config) |
123
+ | `filtering` | Block lists, allow lists, user rules, host lookup |
124
+ | `clients` | Per-client access lists and settings |
125
+ | `dhcp` | DHCP server + static leases |
126
+ | `log` | Query log config + search |
127
+ | `stats` | Query statistics + config |
128
+ | `blocked_services` | Time-scheduled service blocking (Netflix, TikTok, etc.) |
129
+ | `safebrowsing` | Google Safe Browsing toggle |
130
+ | `parental` | Parental control toggle |
131
+ | `safesearch` | Safe search enforcement |
132
+ | `rewrite` | Local DNS rewrites (map domains to IPs) |
133
+ | `tls` | HTTPS / DNS-over-TLS / DNS-over-HTTPS config |
134
+ | `mobileconfig` | Generate iOS/macOS mobile config profiles |
135
+ | `i18n` | UI language |
136
+
137
+ ## Real Example: Bootstrap a New AdGuard Home Instance
138
+
139
+ ```bash
140
+ #!/usr/bin/env bash
141
+ set -e
142
+
143
+ export ADGUARD_HOME_CLI_BASE_URL=http://new-adguard:3000/control
144
+ export ADGUARD_HOME_CLI_USERNAME=admin
145
+ export ADGUARD_HOME_CLI_PASSWORD=$ADMIN_PASSWORD
146
+
147
+ # Add block lists
148
+ adguard-home-cli filtering add-url --name "OISD" --url "https://big.oisd.nl/" --whitelist false
149
+ adguard-home-cli filtering add-url --name "StevenBlack" --url "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts" --whitelist false
150
+
151
+ # Refresh
152
+ adguard-home-cli filtering refresh
153
+
154
+ # Add local rewrites
155
+ adguard-home-cli rewrite add --domain router.lan --answer 192.168.1.1
156
+ adguard-home-cli rewrite add --domain nas.lan --answer 192.168.1.20
157
+
158
+ # Enable safe browsing + parental
159
+ adguard-home-cli safebrowsing enable
160
+ adguard-home-cli parental enable
161
+
162
+ # Verify
163
+ adguard-home-cli global status --output-format json | jq .protection_enabled
164
+ ```
165
+
166
+ ## How It Works
167
+
168
+ This package is a thin wrapper:
169
+ - Embeds the AdGuard Home OpenAPI spec (`spec.yaml`)
170
+ - Delegates CLI generation to [openapi-cli-gen](https://github.com/shivaam/openapi-cli-gen) at runtime
171
+
172
+ Since it's spec-driven, new AdGuard Home endpoints show up automatically on regeneration — no manual wrapping.
173
+
174
+ ## License
175
+
176
+ MIT. Not affiliated with AdGuard — this is an unofficial community CLI built on top of their public OpenAPI spec.
adguard_home_cli-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,45 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "adguard-home-cli"
7
+ version = "0.1.0"
8
+ description = "A full-coverage CLI for AdGuard Home, generated from its official OpenAPI spec"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Shivam Rastogi" },
14
+ ]
15
+ keywords = ["cli", "openapi", "rest", "api", "generated"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Environment :: Console",
19
+ "Intended Audience :: Developers",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Operating System :: OS Independent",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3 :: Only",
24
+ "Programming Language :: Python :: 3.10",
25
+ "Programming Language :: Python :: 3.11",
26
+ "Programming Language :: Python :: 3.12",
27
+ "Programming Language :: Python :: 3.13",
28
+ "Topic :: Software Development",
29
+ "Topic :: Utilities",
30
+ ]
31
+ dependencies = [
32
+ "openapi-cli-gen>=0.0.14",
33
+ ]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/shivaam/openapi-cli-gen"
37
+ Source = "https://github.com/shivaam/openapi-cli-gen/tree/main/wrappers/adguard-home-cli"
38
+ Issues = "https://github.com/shivaam/openapi-cli-gen/issues"
39
+ Generator = "https://github.com/shivaam/openapi-cli-gen"
40
+
41
+ [project.scripts]
42
+ adguard-home-cli = "adguard_home_cli.cli:main"
43
+
44
+ [tool.hatch.build.targets.wheel]
45
+ packages = ["src/adguard_home_cli"]
adguard_home_cli-0.1.0/src/adguard_home_cli/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """adguard-home-cli CLI — generated by openapi-cli-gen."""
adguard_home_cli-0.1.0/src/adguard_home_cli/cli.py ADDED
@@ -0,0 +1,20 @@
1
+ import os
2
+ from pathlib import Path
3
+ from openapi_cli_gen import build_cli
4
+
5
+ # Base URL: override via ADGUARD_HOME_CLI_BASE_URL env var, fall back to spec default
6
+ _base_url = os.environ.get("ADGUARD_HOME_CLI_BASE_URL") or "http://localhost:3000/control"
7
+
8
+ app = build_cli(
9
+ spec=Path(__file__).parent / "spec.yaml",
10
+ name="adguard-home-cli",
11
+ base_url=_base_url,
12
+ )
13
+
14
+
15
+ def main():
16
+ app()
17
+
18
+
19
+ if __name__ == "__main__":
20
+ main()