iptime-cli
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.
Unofficial. Not affiliated with, endorsed by or supported by EFM Networks. ipTIME is their trademark.
$ iptime clients
IP MAC NAME LINK LEASE LEFT RESERVED
192.168.0.10 AA:BB:CC:00:00:01 desktop lan2 wired static
192.168.0.11 AA:BB:CC:00:00:02 nas lan4 wired 22h 13m yes
192.168.0.20 AA:BB:CC:00:00:03 laptop 5g.1 -48 dBm 1h 46m
192.168.0.21 AA:BB:CC:00:00:04 phone 5g.1 -61 dBm 53m 20s
192.168.0.30 AA:BB:CC:00:00:05 smart-plug 2g.1 -70 dBm 19h 26m
(Sample output from the bundled fake router, with made-up devices.)
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.
Why
- Everything the admin page can read, one command away. Clients, leases, reservations, port forwards, Wi-Fi, WAN, firmware (and whether a newer one exists).
- Firmware check and one-command upgrade using the router's own online upgrade, with a wait through the reboot.
- Safe by default. Reads never change anything. Every write asks first, supports
--dry-run, and refuses to run without--yeswhen there is no terminal to ask on. Wi-Fi passwords, which the router returns in clear text, are hidden unless you pass--show-secrets. - A raw escape hatch.
iptime call <method> [params]sends any method;iptime methodslists the 290-odd methods found in the admin bundle, with the firmware they were seen on. - Standard library only. No dependencies, Python 3.9+.
- A library too.
Router(host, user, password).call(method, params)plus typed helpers. - A fake router to try it on.
python -m iptime_cli.fake_routerserves made-up data, so you can run every example below without touching your router.
Install
$ pipx install iptime-cli # recommended: isolated, on PATH
$ uvx iptime-cli --help # or run without installing
$ pip install iptime-cli # inside a project
Configure
Settings are read in this order: command-line flag, environment variable, config file, default.
| Setting | Flag | Environment | Config file key | Default |
|---|---|---|---|---|
| Router address | --host |
IPTIME_HOST |
host |
192.168.0.1 |
| Admin user | --user |
IPTIME_USER |
user |
admin |
| Admin password | — | IPTIME_PASSWORD |
password |
asked on the terminal |
The config file is ~/.config/iptime-cli/config on macOS and Linux, %APPDATA%\iptime-cli\config on Windows (or --config FILE, or IPTIME_CONFIG):
host = 192.168.0.1
user = admin
password = change-me
Keep it private: chmod 600 ~/.config/iptime-cli/config. The tool warns on stderr when a file with a password is readable by others (macOS and Linux; on Windows your user profile's permissions protect it). 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.
Logging in may end an open browser admin session. The router allows few simultaneous admin sessions. The CLI logs out when it finishes.
Usage
Global options go before or after the command. --json turns any read into JSON for scripts.
Try it without a router
$ python -m iptime_cli.fake_router --port 8080 &
$ export IPTIME_HOST=127.0.0.1:8080 IPTIME_PASSWORD=secret
info
$ iptime info
Model ipTIME FAKE-1000
Firmware 16.000 (built 2026.01.01 00:00:00)
Latest firmware 16.010 (update available)
Uptime 1d 2h 3m
LAN 192.168.0.1 / 255.255.255.0
DHCP pool 192.168.0.2 - 192.168.0.254
WAN dhcp 203.0.113.7 gateway 203.0.113.1 up
WAN link 1000f
iptime firmware upgrade installs it (see below).
clients
Every device the router sees, wired and Wi-Fi, merged with DHCP lease and reservation data. --wireless and --wired filter.
$ iptime clients --wireless
IP MAC NAME LINK LEASE LEFT RESERVED
192.168.0.20 AA:BB:CC:00:00:03 laptop 5g.1 -48 dBm 1h 46m
192.168.0.21 AA:BB:CC:00:00:04 phone 5g.1 -61 dBm 53m 20s
192.168.0.30 AA:BB:CC:00:00:05 smart-plug 2g.1 -70 dBm 19h 26m
wan and wifi
$ iptime wan
Type dhcp
Status up (ok)
IP 203.0.113.7
Mask 255.255.255.0
Gateway 203.0.113.1
DNS 198.51.100.2, 198.51.100.3
MAC AA:BB:CC:00:10:02
MTU 1500
Link speed 1000f
Connected for 1d 2h 1m
Received 2.9 TB
Sent 300.0 GB
$ iptime wifi
BSS SSID BAND CH SECURITY ON HIDDEN CLIENTS
2g.1 example-2.4G 2g 11ax/40MHz 6 wpa2psk_aes yes 1
5g.1 example-5G 5g 11ax/80MHz 36 wpa2psk_aes yes 2
iptime wifi --show-secrets adds a PASSWORD column.
port
$ iptime port list
NAME PROTO EXTERNAL TARGET INTERNAL ON
Web server tcp 8080 192.168.0.10 80 yes
Game range udp 27000-27010 192.168.0.20 27000-27010 no
$ iptime port add "Test rule" --target 192.168.0.10 --ext 9000-9005 --proto udp --dry-run
dry run, nothing sent:
POST http://127.0.0.1:8080/cgi/service.cgi
{"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}}}
$ iptime port add "Test rule" --target 192.168.0.10 --ext 9000 --int 90 --yes
ok, rules now:
NAME PROTO EXTERNAL TARGET INTERNAL ON
Web server tcp 8080 192.168.0.10 80 yes
Game range udp 27000-27010 192.168.0.20 27000-27010 no
Test rule tcp 9000 192.168.0.10 90 yes
$ iptime port rm "Test rule" --yes
ok, rules now:
NAME PROTO EXTERNAL TARGET INTERNAL ON
Web server tcp 8080 192.168.0.10 80 yes
Game range udp 27000-27010 192.168.0.20 27000-27010 no
--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.
dhcp
$ iptime dhcp list
IP MAC NAME STATE LEASE LEFT
192.168.0.11 AA:BB:CC:00:00:02 NAS reserved+leased 22h 13m
192.168.0.20 AA:BB:CC:00:00:03 laptop leased 1h 46m
192.168.0.21 AA:BB:CC:00:00:04 phone leased 53m 20s
192.168.0.30 AA:BB:CC:00:00:05 smart-plug leased 19h 26m
$ iptime dhcp reserve aa-bb-cc-00-00-09 192.168.0.40 --name printer --dry-run
dry run, nothing sent:
POST http://127.0.0.1:8080/cgi/service.cgi
{"method": "dhcpd/reservedaddr/add", "params": {"ntag": "lan", "mac": "AA:BB:CC:00:00:09", "ip": "192.168.0.40", "desc": "printer"}}
$ iptime dhcp unreserve AA:BB:CC:00:00:09 --yes
ok: "done"
MACs may be written with : or -, in any case.
remote-admin
With no argument it shows the state; on and off change it.
$ iptime remote-admin
LAN admin HTTP port 80
Remote HTTP off, port 8080
Remote HTTPS off, port 8443
$ iptime remote-admin on --dry-run
warning: this opens the router's admin page to the internet.
dry run, nothing sent:
POST http://127.0.0.1:8080/cgi/service.cgi
{"method": "http/config", "params": {"remotehttp_flag": true, "remotehttp_port": 8080, "commit": true}}
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.
firmware
$ iptime firmware check
Running 16.000 (built 2026.01.01 00:00:00)
Latest 16.010
State update available
$ iptime firmware upgrade --dry-run
dry run, nothing sent (16.000 -> 16.010):
POST http://127.0.0.1:8080/cgi/service.cgi
{"method": "firmware/upgrade/prepare", "params": {"method": "auto"}}
POST http://127.0.0.1:8080/cgi/service.cgi
{"method": "firmware/upgrade/online"}
$ iptime firmware upgrade --yes
[17:31:34] upgrade requested: 16.000 -> 16.010
[17:31:34] stage: starting
[17:31:35] stage: checking
[17:31:36] stage: downloading
[17:31:38] stage: waiting
[17:31:39] stage: writing
[17:31:42] router is rebooting (unreachable)
[17:31:45] stage: idle
firmware upgraded 16.000 -> 16.010 in 11s
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.
- 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.
upgradeasks first;--yesskips the question,--dry-runprints the two requests and sends nothing.--if-availableexits 0 and prints nothing when the router is already current.--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.- The progress lines go to stderr; with
--jsononly the final result is printed. - If the router reports a failed upgrade (
download,format,versionorinternal), the command stops with that reason.
reboot
iptime reboot asks, then reboots the router; the connection drops for a minute or two. --dry-run shows the request.
call and methods
$ iptime call dhcpd/reservedaddr/show lan
{
"result": [
{
"mac": "AA:BB:CC:00:00:02",
"ip": "192.168.0.11",
"desc": "NAS"
}
]
}
$ iptime methods --seen
METHOD KIND STATUS FIRMWARE NOTE
admin/auth/info read ok 16.00.0 login policy: auth mode, session timeout, captcha use/tolerance
conn/info read ok 16.00.0 connection-tracking totals per LAN host
...
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).
Library
from iptime_cli import Router
with Router("192.168.0.1", "admin", "change-me") as router: # logs out on exit
for st in router.stations(): # typed: Station
print(st.ip, st.mac, st.name, st.link)
print(router.call("firmware/version/latest")) # any method; returns "result"
192.168.0.10 AA:BB:CC:00:00:01 desktop wired
192.168.0.11 AA:BB:CC:00:00:02 nas wired
192.168.0.20 AA:BB:CC:00:00:03 laptop wireless
192.168.0.21 AA:BB:CC:00:00:04 phone wireless
192.168.0.30 AA:BB:CC:00:00:05 smart-plug wireless
16.010
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.
Options
| Option | Meaning |
|---|---|
--host, --user, --config FILE |
connection settings (see Configure) |
--timeout SECONDS |
per-request timeout, default 15 |
--insecure |
do not verify a self-signed https certificate |
--json |
print JSON instead of a table |
--show-secrets |
show Wi-Fi passwords (hidden by default) |
--dry-run |
for writes: print the request, send nothing |
-y, --yes |
do not ask before a write |
Exit codes: 0 ok, 1 error (router, login, API), 2 bad usage or bad params JSON.
Errors
| You see | Meaning |
|---|---|
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) |
login failed (wrong user or password?) |
the router refused the login |
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 |
cannot reach ... |
wrong address, router off, or this machine is not allowed to reach the LAN |
Safety notes for writes
- Every write command asks first. Without a terminal it refuses unless
--yesis given;--dry-runnever sends. - Read a write with
--dry-runfirst, then run it. remote-admin onexposes the admin page to the internet. Use a strong password, or do not.port rmdeletes by name; names are exact.dhcp reservetakes one MAC and one IP per call.firmware upgradereboots 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.- Wi-Fi settings are read-only in this version.
iptime callaccepts a method it does not know only with--write.
Tested
| What | Result |
|---|---|
| Router | one ipTIME A5004NS-M, firmware 16.00.0 (build 2026.09.16) |
Read commands (info, clients, wan, wifi, dhcp list, port list, remote-admin, firmware check, call) and firmware upgrade --dry-run |
run against that router |
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 |
| 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 |
| OS | macOS (Python 3.12) against the real router; Windows 11 (Python 3.10) and Ubuntu 24.04 (Python 3.12) against the bundled fake router, installed from PyPI |
| Not tested | Windows and Linux against a real router, other models, other 16.x builds, https admin, old admin UI (refused with an error), Wi-Fi 7 / mesh models |
Other models may differ: on the tested model system/temperature, wireless/mlo/info, port/role, power/status and fan/running are absent.
For AI agents
See AGENTS.md. A ready-made skill is in skill/iptime-cli/SKILL.md.
License
MIT.
Metadata
Release files for iptime-cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iptime_cli-0.1.1.tar.gz | 36.4 kB | Without provenance | Details for iptime_cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iptime_cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iptime_cli-0.1.1-py3-none-any.whl |
Total release size: 69.8 kB
Release files / iptime_cli-0.1.1.tar.gz
| Download URL | iptime_cli-0.1.1.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
703304d83fd007d13b7d6f27fd447379193cdceaf74bfca76157a2b0d33c79f6
|
|
BLAKE2b-256 checksum How to use checksums |
9ed94b264cc43a749dd84f47b117054e3849e6c815dfc28c314b7c48afdd0182
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / iptime_cli-0.1.1-py3-none-any.whl
| Download URL | iptime_cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 33.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
86732ea47cca2452296a26b0f8dfd4c27efdc4e83a62ff073e07247d7be20132
|
|
BLAKE2b-256 checksum How to use checksums |
a3b0c7f37fea8215192ae61238683dce5c35cdc5614d9eaf9d37abc310ae5513
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Security for iptime-cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.