iptime-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.
- iptime_cli-0.1.0/LICENSE +21 -0
- iptime_cli-0.1.0/PKG-INFO +356 -0
- iptime_cli-0.1.0/README.md +333 -0
- iptime_cli-0.1.0/pyproject.toml +39 -0
- iptime_cli-0.1.0/setup.cfg +4 -0
- iptime_cli-0.1.0/src/iptime_cli/__init__.py +7 -0
- iptime_cli-0.1.0/src/iptime_cli/__main__.py +3 -0
- iptime_cli-0.1.0/src/iptime_cli/catalog.py +219 -0
- iptime_cli-0.1.0/src/iptime_cli/cli.py +385 -0
- iptime_cli-0.1.0/src/iptime_cli/client.py +495 -0
- iptime_cli-0.1.0/src/iptime_cli/config.py +85 -0
- iptime_cli-0.1.0/src/iptime_cli/fake_router.py +250 -0
- iptime_cli-0.1.0/src/iptime_cli/render.py +49 -0
- iptime_cli-0.1.0/src/iptime_cli.egg-info/PKG-INFO +356 -0
- iptime_cli-0.1.0/src/iptime_cli.egg-info/SOURCES.txt +16 -0
- iptime_cli-0.1.0/src/iptime_cli.egg-info/dependency_links.txt +1 -0
- iptime_cli-0.1.0/src/iptime_cli.egg-info/entry_points.txt +2 -0
- iptime_cli-0.1.0/src/iptime_cli.egg-info/top_level.txt +1 -0
iptime_cli-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 El Fenomeno
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: iptime-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial command line and Python library for ipTIME routers with the new admin UI (firmware 16.x): clients, DHCP reservations, port forwarding, Wi-Fi, WAN, remote admin. Standard library only.
|
|
5
|
+
Author: El Fenomeno
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/elfenomenokim/iptime-cli
|
|
8
|
+
Project-URL: Repository, https://github.com/elfenomenokim/iptime-cli
|
|
9
|
+
Project-URL: Issues, https://github.com/elfenomenokim/iptime-cli/issues
|
|
10
|
+
Keywords: iptime,router,cli,korea,efm,port-forwarding,dhcp,wifi,home-network
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: System Administrators
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Topic :: System :: Networking
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# iptime-cli
|
|
25
|
+
|
|
26
|
+
[한국어](https://github.com/elfenomenokim/iptime-cli/blob/main/README.ko.md)
|
|
27
|
+
|
|
28
|
+
An unofficial command line and Python library for ipTIME routers that have the new admin UI (firmware 16.x). List connected devices, reserve DHCP addresses, manage port forwarding, check Wi-Fi and WAN, switch remote admin off — from a terminal, a script or an AI agent.
|
|
29
|
+
|
|
30
|
+
> Unofficial. Not affiliated with, endorsed by or supported by EFM Networks. ipTIME is their trademark.
|
|
31
|
+
|
|
32
|
+
```console
|
|
33
|
+
$ iptime clients
|
|
34
|
+
IP MAC NAME LINK LEASE LEFT RESERVED
|
|
35
|
+
192.168.0.10 AA:BB:CC:00:00:01 desktop lan2 wired static
|
|
36
|
+
192.168.0.11 AA:BB:CC:00:00:02 nas lan4 wired 22h 13m yes
|
|
37
|
+
192.168.0.20 AA:BB:CC:00:00:03 laptop 5g.1 -48 dBm 1h 46m
|
|
38
|
+
192.168.0.21 AA:BB:CC:00:00:04 phone 5g.1 -61 dBm 53m 20s
|
|
39
|
+
192.168.0.30 AA:BB:CC:00:00:05 smart-plug 2g.1 -70 dBm 19h 26m
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
(Sample output from the bundled fake router, with made-up devices.)
|
|
43
|
+
|
|
44
|
+
ipTIME is the most common home router brand in Korea and it has no public API. Its new admin page (a Flutter app served at `/ui/`) talks to the router through one JSON endpoint, `POST /cgi/service.cgi {"method": ..., "params": ...}`. This tool speaks that same protocol. The only earlier public work we found is an npm package for the old UI on firmware 14.x.
|
|
45
|
+
|
|
46
|
+
## Why
|
|
47
|
+
|
|
48
|
+
- **Everything the admin page can read, one command away.** Clients, leases, reservations, port forwards, Wi-Fi, WAN, firmware (and whether a newer one exists).
|
|
49
|
+
- **Firmware check and one-command upgrade** using the router's own online upgrade, with a wait through the reboot.
|
|
50
|
+
- **Safe by default.** Reads never change anything. Every write asks first, supports `--dry-run`, and refuses to run without `--yes` when there is no terminal to ask on. Wi-Fi passwords, which the router returns in clear text, are hidden unless you pass `--show-secrets`.
|
|
51
|
+
- **A raw escape hatch.** `iptime call <method> [params]` sends any method; `iptime methods` lists the 290-odd methods found in the admin bundle, with the firmware they were seen on.
|
|
52
|
+
- **Standard library only.** No dependencies, Python 3.9+.
|
|
53
|
+
- **A library too.** `Router(host, user, password).call(method, params)` plus typed helpers.
|
|
54
|
+
- **A fake router to try it on.** `python -m iptime_cli.fake_router` serves made-up data, so you can run every example below without touching your router.
|
|
55
|
+
|
|
56
|
+
## Install
|
|
57
|
+
|
|
58
|
+
```console
|
|
59
|
+
$ pipx install iptime-cli # recommended: isolated, on PATH
|
|
60
|
+
$ uvx iptime-cli --help # or run without installing
|
|
61
|
+
$ pip install iptime-cli # inside a project
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Configure
|
|
65
|
+
|
|
66
|
+
Settings are read in this order: command-line flag, environment variable, config file, default.
|
|
67
|
+
|
|
68
|
+
| Setting | Flag | Environment | Config file key | Default |
|
|
69
|
+
|---|---|---|---|---|
|
|
70
|
+
| Router address | `--host` | `IPTIME_HOST` | `host` | `192.168.0.1` |
|
|
71
|
+
| Admin user | `--user` | `IPTIME_USER` | `user` | `admin` |
|
|
72
|
+
| Admin password | — | `IPTIME_PASSWORD` | `password` | asked on the terminal |
|
|
73
|
+
|
|
74
|
+
The config file is `~/.config/iptime-cli/config` (or `--config FILE`, or `IPTIME_CONFIG`):
|
|
75
|
+
|
|
76
|
+
```ini
|
|
77
|
+
host = 192.168.0.1
|
|
78
|
+
user = admin
|
|
79
|
+
password = change-me
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Keep it private: `chmod 600 ~/.config/iptime-cli/config`. The tool warns on stderr when a file with a password is readable by others. A file of `IPTIME_ADMIN_URL=`, `IPTIME_ADMIN_USER=`, `IPTIME_ADMIN_PASSWORD=` lines (or `IPTIME_HOST=` ...) works too. `--host` accepts `192.168.0.1`, `192.168.0.1:8080` or a full URL.
|
|
83
|
+
|
|
84
|
+
> **Logging in may end an open browser admin session.** The router allows few simultaneous admin sessions. The CLI logs out when it finishes.
|
|
85
|
+
|
|
86
|
+
## Usage
|
|
87
|
+
|
|
88
|
+
Global options go before or after the command. `--json` turns any read into JSON for scripts.
|
|
89
|
+
|
|
90
|
+
### Try it without a router
|
|
91
|
+
|
|
92
|
+
```console
|
|
93
|
+
$ python -m iptime_cli.fake_router --port 8080 &
|
|
94
|
+
$ export IPTIME_HOST=127.0.0.1:8080 IPTIME_PASSWORD=secret
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### info
|
|
98
|
+
|
|
99
|
+
```console
|
|
100
|
+
$ iptime info
|
|
101
|
+
Model ipTIME FAKE-1000
|
|
102
|
+
Firmware 16.000 (built 2026.01.01 00:00:00)
|
|
103
|
+
Latest firmware 16.010 (update available)
|
|
104
|
+
Uptime 1d 2h 3m
|
|
105
|
+
LAN 192.168.0.1 / 255.255.255.0
|
|
106
|
+
DHCP pool 192.168.0.2 - 192.168.0.254
|
|
107
|
+
WAN dhcp 203.0.113.7 gateway 203.0.113.1 up
|
|
108
|
+
WAN link 1000f
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`iptime firmware upgrade` installs it (see below).
|
|
112
|
+
|
|
113
|
+
### clients
|
|
114
|
+
|
|
115
|
+
Every device the router sees, wired and Wi-Fi, merged with DHCP lease and reservation data. `--wireless` and `--wired` filter.
|
|
116
|
+
|
|
117
|
+
```console
|
|
118
|
+
$ iptime clients --wireless
|
|
119
|
+
IP MAC NAME LINK LEASE LEFT RESERVED
|
|
120
|
+
192.168.0.20 AA:BB:CC:00:00:03 laptop 5g.1 -48 dBm 1h 46m
|
|
121
|
+
192.168.0.21 AA:BB:CC:00:00:04 phone 5g.1 -61 dBm 53m 20s
|
|
122
|
+
192.168.0.30 AA:BB:CC:00:00:05 smart-plug 2g.1 -70 dBm 19h 26m
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### wan and wifi
|
|
126
|
+
|
|
127
|
+
```console
|
|
128
|
+
$ iptime wan
|
|
129
|
+
Type dhcp
|
|
130
|
+
Status up (ok)
|
|
131
|
+
IP 203.0.113.7
|
|
132
|
+
Mask 255.255.255.0
|
|
133
|
+
Gateway 203.0.113.1
|
|
134
|
+
DNS 198.51.100.2, 198.51.100.3
|
|
135
|
+
MAC AA:BB:CC:00:10:02
|
|
136
|
+
MTU 1500
|
|
137
|
+
Link speed 1000f
|
|
138
|
+
Connected for 1d 2h 1m
|
|
139
|
+
Received 2.9 TB
|
|
140
|
+
Sent 300.0 GB
|
|
141
|
+
|
|
142
|
+
$ iptime wifi
|
|
143
|
+
BSS SSID BAND CH SECURITY ON HIDDEN CLIENTS
|
|
144
|
+
2g.1 example-2.4G 2g 11ax/40MHz 6 wpa2psk_aes yes 1
|
|
145
|
+
5g.1 example-5G 5g 11ax/80MHz 36 wpa2psk_aes yes 2
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`iptime wifi --show-secrets` adds a PASSWORD column.
|
|
149
|
+
|
|
150
|
+
### port
|
|
151
|
+
|
|
152
|
+
```console
|
|
153
|
+
$ iptime port list
|
|
154
|
+
NAME PROTO EXTERNAL TARGET INTERNAL ON
|
|
155
|
+
Web server tcp 8080 192.168.0.10 80 yes
|
|
156
|
+
Game range udp 27000-27010 192.168.0.20 27000-27010 no
|
|
157
|
+
|
|
158
|
+
$ iptime port add "Test rule" --target 192.168.0.10 --ext 9000-9005 --proto udp --dry-run
|
|
159
|
+
dry run, nothing sent:
|
|
160
|
+
POST http://127.0.0.1:8080/cgi/service.cgi
|
|
161
|
+
{"method": "portforward/add", "params": {"name": "Test rule", "active": true, "protocol": "udp", "target": "192.168.0.10", "src": {"start": 9000, "end": 9005}, "dst": {"start": 9000, "end": 9005}}}
|
|
162
|
+
|
|
163
|
+
$ iptime port add "Test rule" --target 192.168.0.10 --ext 9000 --int 90 --yes
|
|
164
|
+
ok, rules now:
|
|
165
|
+
NAME PROTO EXTERNAL TARGET INTERNAL ON
|
|
166
|
+
Web server tcp 8080 192.168.0.10 80 yes
|
|
167
|
+
Game range udp 27000-27010 192.168.0.20 27000-27010 no
|
|
168
|
+
Test rule tcp 9000 192.168.0.10 90 yes
|
|
169
|
+
|
|
170
|
+
$ iptime port rm "Test rule" --yes
|
|
171
|
+
ok, rules now:
|
|
172
|
+
NAME PROTO EXTERNAL TARGET INTERNAL ON
|
|
173
|
+
Web server tcp 8080 192.168.0.10 80 yes
|
|
174
|
+
Game range udp 27000-27010 192.168.0.20 27000-27010 no
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
`--ext` is the port on the WAN side, `--int` the port on the target (default: same as `--ext`). `--proto` is `tcp`, `udp` or `tcpudp`. `iptime port list --upnp` shows the rules programs created through UPnP; `port rm` only removes your own rules.
|
|
178
|
+
|
|
179
|
+
### dhcp
|
|
180
|
+
|
|
181
|
+
```console
|
|
182
|
+
$ iptime dhcp list
|
|
183
|
+
IP MAC NAME STATE LEASE LEFT
|
|
184
|
+
192.168.0.11 AA:BB:CC:00:00:02 NAS reserved+leased 22h 13m
|
|
185
|
+
192.168.0.20 AA:BB:CC:00:00:03 laptop leased 1h 46m
|
|
186
|
+
192.168.0.21 AA:BB:CC:00:00:04 phone leased 53m 20s
|
|
187
|
+
192.168.0.30 AA:BB:CC:00:00:05 smart-plug leased 19h 26m
|
|
188
|
+
|
|
189
|
+
$ iptime dhcp reserve aa-bb-cc-00-00-09 192.168.0.40 --name printer --dry-run
|
|
190
|
+
dry run, nothing sent:
|
|
191
|
+
POST http://127.0.0.1:8080/cgi/service.cgi
|
|
192
|
+
{"method": "dhcpd/reservedaddr/add", "params": {"ntag": "lan", "mac": "AA:BB:CC:00:00:09", "ip": "192.168.0.40", "desc": "printer"}}
|
|
193
|
+
|
|
194
|
+
$ iptime dhcp unreserve AA:BB:CC:00:00:09 --yes
|
|
195
|
+
ok: "done"
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
MACs may be written with `:` or `-`, in any case.
|
|
199
|
+
|
|
200
|
+
### remote-admin
|
|
201
|
+
|
|
202
|
+
With no argument it shows the state; `on` and `off` change it.
|
|
203
|
+
|
|
204
|
+
```console
|
|
205
|
+
$ iptime remote-admin
|
|
206
|
+
LAN admin HTTP port 80
|
|
207
|
+
Remote HTTP off, port 8080
|
|
208
|
+
Remote HTTPS off, port 8443
|
|
209
|
+
|
|
210
|
+
$ iptime remote-admin on --dry-run
|
|
211
|
+
warning: this opens the router's admin page to the internet.
|
|
212
|
+
dry run, nothing sent:
|
|
213
|
+
POST http://127.0.0.1:8080/cgi/service.cgi
|
|
214
|
+
{"method": "http/config", "params": {"remotehttp_flag": true, "remotehttp_port": 8080, "commit": true}}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`off` turns only remote (WAN) HTTP admin off; the admin page on the LAN stays reachable. `on` uses the stored remote port unless you pass `--port`.
|
|
218
|
+
|
|
219
|
+
### firmware
|
|
220
|
+
|
|
221
|
+
```console
|
|
222
|
+
$ iptime firmware check
|
|
223
|
+
Running 16.000 (built 2026.01.01 00:00:00)
|
|
224
|
+
Latest 16.010
|
|
225
|
+
State update available
|
|
226
|
+
|
|
227
|
+
$ iptime firmware upgrade --dry-run
|
|
228
|
+
dry run, nothing sent (16.000 -> 16.010):
|
|
229
|
+
POST http://127.0.0.1:8080/cgi/service.cgi
|
|
230
|
+
{"method": "firmware/upgrade/prepare", "params": {"method": "auto"}}
|
|
231
|
+
POST http://127.0.0.1:8080/cgi/service.cgi
|
|
232
|
+
{"method": "firmware/upgrade/online"}
|
|
233
|
+
|
|
234
|
+
$ iptime firmware upgrade --yes
|
|
235
|
+
[17:31:34] upgrade requested: 16.000 -> 16.010
|
|
236
|
+
[17:31:34] stage: starting
|
|
237
|
+
[17:31:35] stage: checking
|
|
238
|
+
[17:31:36] stage: downloading
|
|
239
|
+
[17:31:38] stage: waiting
|
|
240
|
+
[17:31:39] stage: writing
|
|
241
|
+
[17:31:42] router is rebooting (unreachable)
|
|
242
|
+
[17:31:45] stage: idle
|
|
243
|
+
firmware upgraded 16.000 -> 16.010 in 11s
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`check` compares the running version with the newest one the router itself reports. `upgrade` uses only the vendor's own online upgrade: the router downloads the image itself (nothing is uploaded from your machine), flashes it and reboots. It sends the two calls the admin page's "upgrade now" button makes, polls the upgrade status, waits through the outage, logs in again and prints old -> new.
|
|
247
|
+
|
|
248
|
+
- **Expect an outage.** The router reboots; the network drops for a few minutes (the router reports about four minutes of flashing). Run it by hand at a quiet time, not while someone depends on the connection.
|
|
249
|
+
- `upgrade` asks first; `--yes` skips the question, `--dry-run` prints the two requests and sends nothing.
|
|
250
|
+
- `--if-available` exits 0 and prints nothing when the router is already current.
|
|
251
|
+
- `--wait-timeout SECONDS` (default 1800) is how long to wait for the router to come back on a new version; `--poll SECONDS` (default 10) is the status interval. If the router never comes back in time the command exits 1 and says so; check the router yourself.
|
|
252
|
+
- The progress lines go to stderr; with `--json` only the final result is printed.
|
|
253
|
+
- If the router reports a failed upgrade (`download`, `format`, `version` or `internal`), the command stops with that reason.
|
|
254
|
+
|
|
255
|
+
### reboot
|
|
256
|
+
|
|
257
|
+
`iptime reboot` asks, then reboots the router; the connection drops for a minute or two. `--dry-run` shows the request.
|
|
258
|
+
|
|
259
|
+
### call and methods
|
|
260
|
+
|
|
261
|
+
```console
|
|
262
|
+
$ iptime call dhcpd/reservedaddr/show lan
|
|
263
|
+
{
|
|
264
|
+
"result": [
|
|
265
|
+
{
|
|
266
|
+
"mac": "AA:BB:CC:00:00:02",
|
|
267
|
+
"ip": "192.168.0.11",
|
|
268
|
+
"desc": "NAS"
|
|
269
|
+
}
|
|
270
|
+
]
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
$ iptime methods --seen
|
|
274
|
+
METHOD KIND STATUS FIRMWARE NOTE
|
|
275
|
+
admin/auth/info read ok 16.00.0 login policy: auth mode, session timeout, captcha use/tolerance
|
|
276
|
+
conn/info read ok 16.00.0 connection-tracking totals per LAN host
|
|
277
|
+
...
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
`call` prints the router's whole answer (`{"result": ...}` or `{"error": ...}`) and exits 1 on an error object. Params are JSON; a bare word such as `lan` is sent as a string. A method that is not a read needs `--write` (or `--dry-run`). `iptime methods` needs no router; `--kind read|write|danger|session` and `--seen` filter. STATUS means `ok` (called on real hardware, read-only), `absent` (the model answered "Method not found" or "Config error"), `used` (a write method that an earlier hand-written script sent to real hardware) or `bundle` (named in the admin bundle, never called by us).
|
|
281
|
+
|
|
282
|
+
### Library
|
|
283
|
+
|
|
284
|
+
```python
|
|
285
|
+
from iptime_cli import Router
|
|
286
|
+
|
|
287
|
+
with Router("192.168.0.1", "admin", "change-me") as router: # logs out on exit
|
|
288
|
+
for st in router.stations(): # typed: Station
|
|
289
|
+
print(st.ip, st.mac, st.name, st.link)
|
|
290
|
+
print(router.call("firmware/version/latest")) # any method; returns "result"
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
```text
|
|
294
|
+
192.168.0.10 AA:BB:CC:00:00:01 desktop wired
|
|
295
|
+
192.168.0.11 AA:BB:CC:00:00:02 nas wired
|
|
296
|
+
192.168.0.20 AA:BB:CC:00:00:03 laptop wireless
|
|
297
|
+
192.168.0.21 AA:BB:CC:00:00:04 phone wireless
|
|
298
|
+
192.168.0.30 AA:BB:CC:00:00:05 smart-plug wireless
|
|
299
|
+
16.010
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Helpers: `product()`, `firmware()`, `system()`, `wan()`, `lan()`, `stations()`, `leases()`, `reservations()`, `wifi()`, `port_forwards()`, `remote_admin()`; writes `add_port_forward()`, `del_port_forward()`, `reserve()`, `unreserve()`, `set_remote_admin()`, `upgrade_firmware()`, `reboot()`. `call()` returns the `result` and raises `ApiError` on an error object; `call_raw()` returns the whole answer. Errors derive from `IptimeError`: `ConnectError`, `OldUiError`, `LoginError` (`CaptchaError`, `LockoutError`), `ApiError`, `UpgradeError`. `Router(..., dry_run=True)` makes every non-read call return the request instead of sending it.
|
|
303
|
+
|
|
304
|
+
## Options
|
|
305
|
+
|
|
306
|
+
| Option | Meaning |
|
|
307
|
+
|---|---|
|
|
308
|
+
| `--host`, `--user`, `--config FILE` | connection settings (see Configure) |
|
|
309
|
+
| `--timeout SECONDS` | per-request timeout, default 15 |
|
|
310
|
+
| `--insecure` | do not verify a self-signed https certificate |
|
|
311
|
+
| `--json` | print JSON instead of a table |
|
|
312
|
+
| `--show-secrets` | show Wi-Fi passwords (hidden by default) |
|
|
313
|
+
| `--dry-run` | for writes: print the request, send nothing |
|
|
314
|
+
| `-y`, `--yes` | do not ask before a write |
|
|
315
|
+
|
|
316
|
+
Exit codes: `0` ok, `1` error (router, login, API), `2` bad usage or bad params JSON.
|
|
317
|
+
|
|
318
|
+
## Errors
|
|
319
|
+
|
|
320
|
+
| You see | Meaning |
|
|
321
|
+
|---|---|
|
|
322
|
+
| `old admin UI not supported yet` | the router has no `/ui/` page or does not answer JSON; it runs the old admin UI (firmware 14.x and earlier) |
|
|
323
|
+
| `login failed (wrong user or password?)` | the router refused the login |
|
|
324
|
+
| `the router asks for a captcha` / `the router blocks logins for now` | the router wants a captcha or has blocked logins after failures; wait, or log in once in a browser |
|
|
325
|
+
| `cannot reach ...` | wrong address, router off, or this machine is not allowed to reach the LAN |
|
|
326
|
+
|
|
327
|
+
## Safety notes for writes
|
|
328
|
+
|
|
329
|
+
- Every write command asks first. Without a terminal it refuses unless `--yes` is given; `--dry-run` never sends.
|
|
330
|
+
- Read a write with `--dry-run` first, then run it.
|
|
331
|
+
- `remote-admin on` exposes the admin page to the internet. Use a strong password, or do not.
|
|
332
|
+
- `port rm` deletes by name; names are exact. `dhcp reserve` takes one MAC and one IP per call.
|
|
333
|
+
- `firmware upgrade` reboots the router and drops the network for a few minutes; run it by hand at a quiet time, when nobody needs the connection. Only the router's own online upgrade is used.
|
|
334
|
+
- Wi-Fi settings are read-only in this version.
|
|
335
|
+
- `iptime call` accepts a method it does not know only with `--write`.
|
|
336
|
+
|
|
337
|
+
## Tested
|
|
338
|
+
|
|
339
|
+
| What | Result |
|
|
340
|
+
|---|---|
|
|
341
|
+
| Router | one ipTIME A5004NS-M, firmware 16.00.0 (build 2026.09.16) |
|
|
342
|
+
| Read commands (`info`, `clients`, `wan`, `wifi`, `dhcp list`, `port list`, `remote-admin`, `firmware check`, `call`) and `firmware upgrade --dry-run` | run against that router |
|
|
343
|
+
| Write commands (`port add/rm`, `dhcp reserve/unreserve`, `remote-admin on/off`, `reboot`, `firmware upgrade`) | **only against the bundled fake router**, never against a real one by this package. The request bodies follow what the admin page sends. An earlier hand-written script sent the same port-forward and DHCP-reservation bodies to a real router and they worked; `remote-admin off`, `remote-admin on`, `reboot` and the two firmware-upgrade calls and their status stages were read from the admin bundle and never reached real hardware |
|
|
344
|
+
| Login failures | one wrong login against real hardware: the router answered `{"error": {"code": -31996, "message": "Config error"}}`. Captcha and lockout messages were not observed; those paths are only exercised by the fake router, so their wording is a guess |
|
|
345
|
+
| OS | macOS, Python 3.12 |
|
|
346
|
+
| Not tested | Linux and Windows, other models, other 16.x builds, https admin, old admin UI (refused with an error), Wi-Fi 7 / mesh models |
|
|
347
|
+
|
|
348
|
+
Other models may differ: on the tested model `system/temperature`, `wireless/mlo/info`, `port/role`, `power/status` and `fan/running` are absent.
|
|
349
|
+
|
|
350
|
+
## For AI agents
|
|
351
|
+
|
|
352
|
+
See [AGENTS.md](https://github.com/elfenomenokim/iptime-cli/blob/main/AGENTS.md). A ready-made skill is in `skill/iptime-cli/SKILL.md`.
|
|
353
|
+
|
|
354
|
+
## License
|
|
355
|
+
|
|
356
|
+
MIT.
|