iptime-cli 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,250 @@
1
+ """A tiny fake of the ipTIME admin API with made-up data, to try the CLI without a router.
2
+
3
+ python -m iptime_cli.fake_router --port 8080
4
+ IPTIME_PASSWORD=secret iptime --host 127.0.0.1:8080 clients
5
+
6
+ Not a router: it only knows the methods the CLI uses. Login is ``admin`` / ``secret``.
7
+ Modes for testing error paths: ``--old-ui`` (no /ui/ page), ``--captcha`` (every login asks for a
8
+ captcha), ``--lockout`` (every login is blocked). Writes change the in-memory data only.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import copy
14
+ import json
15
+ import secrets
16
+ import time
17
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
18
+
19
+ PASSWORD = "secret"
20
+
21
+
22
+ def fresh_state() -> dict:
23
+ stations = [
24
+ ("AA:BB:CC:00:00:01", "192.168.0.10", "desktop", "wired", {"port": "lan2", "link": 1000, "down_bytes": 52428800, "up_bytes": 10485760}, "static"),
25
+ ("AA:BB:CC:00:00:02", "192.168.0.11", "nas", "wired", {"port": "lan4", "link": 1000, "down_bytes": 9437184000, "up_bytes": 2147483648}, "dhcp"),
26
+ ("AA:BB:CC:00:00:03", "192.168.0.20", "laptop", "wireless", {"bss": "5g.1", "duration": 3600, "rssi": -48, "normal_power": 100, "down_speed": 866, "up_speed": 780, "down_bytes": 734003200, "up_bytes": 104857600}, "dhcp"),
27
+ ("AA:BB:CC:00:00:04", "192.168.0.21", "phone", "wireless", {"bss": "5g.1", "duration": 1200, "rssi": -61, "normal_power": 100, "down_speed": 433, "up_speed": 390, "down_bytes": 31457280, "up_bytes": 5242880}, "dhcp"),
28
+ ("AA:BB:CC:00:00:05", "192.168.0.30", "smart-plug", "wireless", {"bss": "2g.1", "duration": 86400, "rssi": -70, "normal_power": 100, "down_speed": 72, "up_speed": 72, "down_bytes": 1048576, "up_bytes": 524288}, "dhcp"),
29
+ ]
30
+ return {
31
+ "stations": [{"mac": m, "info": {"ip": ip, "type": t, "name": n, "product_id": "", "product_name": "", "ptype": "normal", "icon": ""},
32
+ "connection": {"type": k, "upstream_mac": "AA:BB:CC:00:10:01", k: d}} for m, ip, n, k, d, t in stations],
33
+ "leases": [{"mac": "AA:BB:CC:00:00:02", "ip": "192.168.0.11", "remaining": 80000, "desc": "nas"},
34
+ {"mac": "AA:BB:CC:00:00:03", "ip": "192.168.0.20", "remaining": 6400, "desc": "laptop"},
35
+ {"mac": "AA:BB:CC:00:00:04", "ip": "192.168.0.21", "remaining": 3200, "desc": "phone"},
36
+ {"mac": "AA:BB:CC:00:00:05", "ip": "192.168.0.30", "remaining": 70000, "desc": "smart-plug"}],
37
+ "reserved": [{"mac": "AA:BB:CC:00:00:02", "ip": "192.168.0.11", "desc": "NAS"}],
38
+ "forwards": [{"name": "Web server", "active": True, "protocol": "tcp", "target": "192.168.0.10", "priority": 1, "fixed": False,
39
+ "src": {"start": 8080}, "dst": {"start": 80}},
40
+ {"name": "Game range", "active": False, "protocol": "udp", "target": "192.168.0.20", "priority": 2, "fixed": False,
41
+ "src": {"start": 27000, "end": 27010}, "dst": {"start": 27000, "end": 27010}}],
42
+ "upnp": [{"name": "example-portmap_udp_40001", "active": True, "protocol": "udp", "target": "192.168.0.21", "priority": 3, "fixed": False,
43
+ "src": {"start": 40001}, "dst": {"start": 40001}}],
44
+ "http": {"mode": "HTTP", "http_port": 80, "remotehttp_flag": False, "remotehttp_port": 8080,
45
+ "https_port": 443, "remotehttps_flag": False, "remotehttps_port": 8443},
46
+ "rebooted": False,
47
+ "fw": "16.000", "up_stage": None, "down_until": 0.0, "outage": 3.0, "drop_sessions": False,
48
+ }
49
+
50
+
51
+ def ok(result):
52
+ return {"result": result}
53
+
54
+
55
+ def err(code, message):
56
+ return {"result": None, "error": {"code": code, "message": message}}
57
+
58
+
59
+ class Handler(BaseHTTPRequestHandler):
60
+ server_version = "FakeIptime/0"
61
+
62
+ def log_message(self, *_):
63
+ pass
64
+
65
+ def _send(self, code, body, ctype="application/json", headers=None):
66
+ raw = body if isinstance(body, bytes) else json.dumps(body).encode()
67
+ self.send_response(code)
68
+ self.send_header("Content-Type", ctype)
69
+ self.send_header("Content-Length", str(len(raw)))
70
+ for k, v in (headers or {}).items():
71
+ self.send_header(k, v)
72
+ self.end_headers()
73
+ self.wfile.write(raw)
74
+
75
+ def _down(self) -> bool:
76
+ """During the simulated reboot the router answers nothing: drop the connection."""
77
+ if time.time() < self.server.state["down_until"]:
78
+ self.close_connection = True
79
+ return True
80
+ return False
81
+
82
+ def do_GET(self):
83
+ if self._down():
84
+ return
85
+ if self.path.startswith("/ui") and not self.server.old_ui:
86
+ self._send(200, b"<html><script src='flutter_bootstrap.js'></script></html>", "text/html")
87
+ else:
88
+ self._send(404 if self.server.old_ui and self.path.startswith("/ui") else 200,
89
+ b"<html>old ipTIME login page</html>", "text/html")
90
+
91
+ def do_POST(self):
92
+ if self._down():
93
+ return
94
+ if self.server.old_ui or self.path != "/cgi/service.cgi":
95
+ return self._send(200, b"<html>old ipTIME login page</html>", "text/html")
96
+ body = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))) or b"{}")
97
+ host = self.headers.get("Host", "")
98
+ if self.headers.get("Origin") != f"http://{host}":
99
+ return self._send(200, err(-32000, "Unauthenticated"))
100
+ method, params = body.get("method", ""), body.get("params")
101
+ srv = self.server
102
+ cookie = self.headers.get("Cookie", "")
103
+ if method == "session/login":
104
+ if srv.captcha:
105
+ return self._send(200, {"result": "captcha", "error": {"code": -1, "message": "captcha required"}})
106
+ if srv.lockout:
107
+ return self._send(200, {"result": "locked", "error": {"code": -2, "message": "too many failures, wait 60 seconds"}})
108
+ if params == {"id": "admin", "pw": PASSWORD}:
109
+ sid = secrets.token_hex(8)
110
+ srv.sessions.add(sid)
111
+ return self._send(200, ok("done"), headers={"Set-Cookie": f"sid={sid}; Path=/"})
112
+ return self._send(200, {"result": "fail", "error": {"code": -3, "message": "wrong id or password"}})
113
+ sid = cookie.split("sid=")[-1].split(";")[0] if "sid=" in cookie else ""
114
+ if sid not in srv.sessions:
115
+ return self._send(200, err(-32000, "Unauthenticated"))
116
+ if method == "session/logout":
117
+ srv.sessions.discard(sid)
118
+ return self._send(200, ok("done"))
119
+ srv.calls.append(body)
120
+ answer = self.dispatch(srv.state, method, params)
121
+ if srv.state["drop_sessions"]:
122
+ srv.sessions.clear()
123
+ srv.state["drop_sessions"] = False
124
+ self._send(200, answer)
125
+
126
+ @staticmethod
127
+ def dispatch(st, method, params):
128
+ if method == "session/info":
129
+ return ok({"type": "session", "ip": "192.168.0.50", "location": "lan", "mac": "AA:BB:CC:00:00:50", "timeout": 1800, "level": "auth"})
130
+ if method == "product/info":
131
+ return ok({"name": "ipTIME FAKE-1000", "id": "fake1000", "company": "EFM Networks", "type": "wireless_router",
132
+ "mac": "AA:BB:CC:00:10:01", "version": "16.00.0", "wan_mac": "AA:BB:CC:00:10:02", "vendor": "efm"})
133
+ if method == "firmware/info":
134
+ return ok({"version": st["fw"], "build_date": "2026.01.01 00:00:00", "snapshot": "0000000"})
135
+ if method == "firmware/version/latest":
136
+ return ok("16.010")
137
+ if method == "firmware/upgrade/prepare":
138
+ return ok("done")
139
+ if method == "firmware/upgrade/online":
140
+ if st["fw"] == "16.010":
141
+ return err(-1, "no need to upgrade")
142
+ st["up_stage"] = 0
143
+ return ok("done")
144
+ if method == "firmware/upgrade/status":
145
+ stages = [{"stage": "starting"}, {"stage": "checking"}, {"stage": "downloading", "downloading": 20},
146
+ {"stage": "downloading", "downloading": 70}, {"stage": "waiting"}, {"stage": "writing"}]
147
+ i = st["up_stage"]
148
+ if i is None:
149
+ return ok({"stage": "idle"})
150
+ if i >= len(stages): # flashing done: the router reboots
151
+ st["fw"], st["up_stage"] = "16.010", None
152
+ st["down_until"] = time.time() + st["outage"]
153
+ st["drop_sessions"] = True
154
+ return ok({"stage": "writing"})
155
+ st["up_stage"] = i + 1
156
+ return ok(stages[i])
157
+ if method == "system/info":
158
+ return ok({"version": "16.00.0", "uptime": 93784, "connected_period": 93700, "wan_link": "1000f",
159
+ "dhcpd": {"enable": True, "startip": "192.168.0.2", "endip": "192.168.0.254"},
160
+ "wireless": [{"band": "2g", "bss": [{"enable": True, "ssid": "example-2.4G", "password": "example-wifi-key"}]}]})
161
+ if method == "network/interface/wan1/info":
162
+ return ok({"type": "dhcp", "ifname": "eth3", "link": True, "status": "up", "protocol_status": "ok",
163
+ "mac": "AA:BB:CC:00:10:02", "ip": "203.0.113.7", "mask": "255.255.255.0", "gateway": "203.0.113.1",
164
+ "mtu": 1500, "device": "eth", "connected_period": 93700})
165
+ if method == "network/interface/lan/info":
166
+ return ok({"type": "static", "ifname": "br0", "link": True, "status": "up", "mac": "AA:BB:CC:00:10:01",
167
+ "ip": "192.168.0.1", "mask": "255.255.255.0", "gateway": "", "mtu": 1500})
168
+ if method == "network/dns/info":
169
+ return ok(["198.51.100.2", "198.51.100.3"])
170
+ if method == "port/link/status":
171
+ return ok([{"type": "wan", "port": 1, "link": "1000f"}, {"type": "lan", "port": 1, "link": "down"}])
172
+ if method == "port/stat/get":
173
+ return ok([{"type": "wan", "port": 1, "rx": {"byte": 3221225472000, "packet": 1}, "tx": {"byte": 322122547200, "packet": 1}}])
174
+ if method == "dhcpd/config/get":
175
+ return ok({"ntag": "lan", "enable": True, "min_ip": "192.168.0.2", "max_ip": "192.168.0.254", "mask": "255.255.255.0",
176
+ "gateway": "192.168.0.1", "dns": ["192.168.0.1"], "leasetime": 86400})
177
+ if method == "dhcpd/lease/show":
178
+ return ok(st["leases"])
179
+ if method == "dhcpd/reservedaddr/show":
180
+ return ok(st["reserved"])
181
+ if method == "dhcpd/reservedaddr/add":
182
+ st["reserved"].append({"mac": params["mac"], "ip": params["ip"], "desc": params["desc"]})
183
+ return ok("done")
184
+ if method == "dhcpd/reservedaddr/del":
185
+ st["reserved"] = [x for x in st["reserved"] if x["mac"] not in params["mac"]]
186
+ return ok("done")
187
+ if method == "network/interface/lan/stations":
188
+ return ok(st["stations"])
189
+ if method == "wireless/band/show":
190
+ return ok([{"band": "2g", "channel": "6", "mode": "11ax", "width": 40}, {"band": "5g", "channel": "36", "mode": "11ax", "width": 80}])
191
+ if method == "wireless/band/info":
192
+ return ok([{"band": "2g", "activated": True, "channel": "6"}, {"band": "5g", "activated": True, "channel": "36"}])
193
+ if method == "wireless/bss/info":
194
+ return ok([{"bss": "2g.1", "run": True}, {"bss": "5g.1", "run": True}])
195
+ if method == "wireless/bss/show":
196
+ return ok([{"bss": "2g.1", "enable": True, "ssid": "example-2.4G", "hide": False, "authenc": "wpa2psk_aes", "password": "example-wifi-key"},
197
+ {"bss": "5g.1", "enable": True, "ssid": "example-5G", "hide": False, "authenc": "wpa2psk_aes", "password": "example-wifi-key"}])
198
+ if method == "portforward/get":
199
+ return ok(st["forwards"] if params == "user" else st["upnp"])
200
+ if method == "portforward/add":
201
+ if any(x["name"] == params["name"] for x in st["forwards"]):
202
+ return err(-100, "duplicate name")
203
+ st["forwards"].append({**params, "priority": len(st["forwards"]) + 1, "fixed": False})
204
+ return ok(st["forwards"])
205
+ if method == "portforward/del":
206
+ st["forwards"] = [x for x in st["forwards"] if x["name"] not in params["list"]]
207
+ return ok(st["forwards"])
208
+ if method == "http/config":
209
+ if params is None:
210
+ return ok(st["http"])
211
+ st["http"]["remotehttp_flag"] = params["remotehttp_flag"]
212
+ st["http"]["remotehttp_port"] = params["remotehttp_port"]
213
+ return ok("done")
214
+ if method == "reboot/now":
215
+ st["rebooted"] = True
216
+ return ok("done")
217
+ if method == "api/has":
218
+ return ok(True)
219
+ return err(-32601, "Method not found")
220
+
221
+
222
+ class FakeServer(ThreadingHTTPServer):
223
+ def __init__(self, addr, old_ui=False, captcha=False, lockout=False):
224
+ super().__init__(addr, Handler)
225
+ self.old_ui, self.captcha, self.lockout = old_ui, captcha, lockout
226
+ self.state, self.sessions, self.calls = fresh_state(), set(), []
227
+
228
+ def snapshot(self) -> dict:
229
+ return copy.deepcopy(self.state)
230
+
231
+
232
+ def main(argv=None):
233
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
234
+ ap.add_argument("--port", type=int, default=8080)
235
+ ap.add_argument("--old-ui", action="store_true")
236
+ ap.add_argument("--captcha", action="store_true")
237
+ ap.add_argument("--lockout", action="store_true")
238
+ ap.add_argument("--upgrade-outage", type=float, default=3.0, help="seconds the router is unreachable after flashing")
239
+ a = ap.parse_args(argv)
240
+ srv = FakeServer(("127.0.0.1", a.port), a.old_ui, a.captcha, a.lockout)
241
+ srv.state["outage"] = a.upgrade_outage
242
+ print(f"fake ipTIME router on http://127.0.0.1:{a.port}/ (admin / {PASSWORD})", flush=True)
243
+ try:
244
+ srv.serve_forever()
245
+ except KeyboardInterrupt:
246
+ pass
247
+
248
+
249
+ if __name__ == "__main__":
250
+ main()
iptime_cli/render.py ADDED
@@ -0,0 +1,49 @@
1
+ """Plain-text tables that line up with Korean (double-width) text."""
2
+ from __future__ import annotations
3
+
4
+ import unicodedata
5
+
6
+
7
+ def width(text: str) -> int:
8
+ return sum(2 if unicodedata.east_asian_width(c) in "WF" else 1 for c in text)
9
+
10
+
11
+ def pad(text: str, size: int) -> str:
12
+ return text + " " * (size - width(text))
13
+
14
+
15
+ def table(headers: list, rows: list) -> str:
16
+ cells = [[("" if c is None else str(c)) for c in row] for row in rows]
17
+ sizes = [max([width(h)] + [width(r[i]) for r in cells]) for i, h in enumerate(headers)]
18
+ lines = [" ".join(pad(h, sizes[i]) for i, h in enumerate(headers)).rstrip()]
19
+ lines += [" ".join(pad(c, sizes[i]) for i, c in enumerate(r)).rstrip() for r in cells]
20
+ return "\n".join(lines)
21
+
22
+
23
+ def pairs(items: list) -> str:
24
+ """Two-column key/value block."""
25
+ size = max(width(k) for k, _ in items)
26
+ return "\n".join(f"{pad(k, size)} {'' if v is None else v}" for k, v in items)
27
+
28
+
29
+ def human_bytes(n) -> str:
30
+ if n is None:
31
+ return ""
32
+ n = float(n)
33
+ for unit in ("B", "KB", "MB", "GB", "TB"):
34
+ if n < 1024 or unit == "TB":
35
+ return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
36
+ n /= 1024
37
+ return str(n)
38
+
39
+
40
+ def human_duration(seconds) -> str:
41
+ if seconds is None:
42
+ return ""
43
+ s = int(seconds)
44
+ d, s = divmod(s, 86400)
45
+ h, s = divmod(s, 3600)
46
+ m, s = divmod(s, 60)
47
+ parts = [f"{d}d" if d else "", f"{h}h" if h or d else "", f"{m}m" if (m or h or d) else "",
48
+ f"{s}s" if not (d or h) else ""]
49
+ return " ".join(p for p in parts if p) or "0s"
@@ -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.