feat(ports): a ports command tree with single-port PoE power-cycling

[jaxzin]

What this adds

A ports command tree for inspecting switch ports and power-cycling a single PoE port.

# which port is my Pi on?
unifi ports find allsky

# bounce PoE on just that port — the rest of the switch is untouched
unifi ports cycle 8c:ed:e1:b0:74:e2 5

Today the only write commands under devices are restart (which reboots the whole switch, bouncing every attached device), locate, and upgrade. Recovering one wedged headless device — a Pi, a camera, an AP — means disrupting everything else on that switch, or leaving the CLI for the controller UI. The underlying API call already exists; this exposes it.

Four subcommands:

ports list [MAC]	one device's ports, or every device's. Paginated, --fields, --live
ports show <MAC> <PORT>	single-port detail, including PoE telemetry the CLI previously discarded
ports find <MAC|IP|NAME>	which switch port a device is attached to
ports cycle <MAC> <PORT>	power-cycle one PoE port

find is what makes cycle usable: cycle needs the switch's MAC and a port_idx, but the operator knows only the device. The mapping is already in port_table[].last_connection.mac — nothing new is fetched.

Design notes

I'd rather explain these up front than have you reverse-engineer them from the diff.

Why a top-level ports noun rather than devices ports cycle. Nesting under the existing devices ports is non-breaking at the CLI level — clap's subcommand_negates_reqs keeps the required MAC positional working, and I verified that. But walk_commands() in src/schema.rs only emits leaf entries, so giving devices ports a child would silently drop it, and its output_fields, from unifi schema. The command would still work when typed; it would just vanish from the machine-readable contract. Fixing that means changing the schema generator's flattening convention, which felt like the wrong thing to bundle into a feature PR for someone else's repo.

devices ports <MAC> is preserved as an alias for ports list <MAC>, routed through the same renderer so the two can't drift. It keeps its bare JSON array shape, while ports list uses the {items, total, limit, offset} envelope your other paginated list commands use. Same fields, different container, and the difference is recorded in the schema note. Its JSON gains exactly two keys — device_mac, device_name — and loses none. There's a committed regression test that fails if either envelope changes or the key sets diverge.

A pre-existing alignment bug, fixed. Your port tables mis-align whenever colour is on. The coloured cell is "\x1b[32mup\x1b[39m" — 13 bytes for 2 visible characters — and {:<6} counts the escape bytes, decides the string already exceeds the width, and emits no padding at all. So up runs straight into the speed column at a TTY, while piped output is fine. devices ports has always done this. I only noticed because my new Connected column inherited it. Cells are now padded by visible width, which fixes devices ports, ports list and ports find together. The uncoloured path is untouched and its existing tests pass unmodified. (1 ports is now 1 port, too.)

Guard rails run before any HTTP. ports cycle refuses a port that isn't PoE-capable, and one whose poe_mode is explicitly "off", rather than firing a no-op at the controller. An absent poe_mode proceeds — the field isn't guaranteed across firmware, and a missing value shouldn't block a legitimate cycle on a port that already passed the port_poe check.

The conflict error kind. unifi schema has advertised {"kind": "conflict", "exit_code": 6, "retryable": false} since the clispec v0.2 upgrade, but nothing in the source ever emitted it — there was no exit-code constant and no ApiError variant. The guard rails above are its first real users, so this PR implements the kind you'd already published rather than adding a new one. The error table itself is unchanged.

A gap I did not fix, deliberately. require_confirmation() never actually prompts — it only hard-errors when stdin isn't a TTY and --yes is absent. So on a terminal, unifi devices restart <mac> reboots a switch immediately, even though the global --yes help text reads "Skip confirmation prompt for destructive commands." The prompt it offers to skip doesn't exist.

I added a real prompt to ports cycle only, in its own commit (the last one), so you can drop or reshape it independently. That does leave ports cycle prompting while its destructive siblings don't. Retrofitting prompts onto the other six commands changes their interactive behaviour, so that's your call, not mine — happy to send it as a separate PR if you want it.

Validation

573 tests, make check clean. Tested against a live UniFi controller (UCG-Max, UniFi OS) across a USW Pro XG 8 PoE, a USW Lite 16 PoE and a USW Lite 8 PoE.

Live testing changed the code twice. Both changes are in this branch.

1. It found a missing guard rail. I fired a cycle at a port that passed both of my checks — port_poe: true, poe_mode: "auto", nothing attached — and the controller rejected it:

HTTP 400  {"meta":{"rc":"error","port":4,"msg":"api.err.InvalidTargetPort"}}

which surfaced as kind: api_error, exit 5 — and your schema advertises api_error as "retryable": true, so an agent following the contract would retry something that can never succeed. The port was PoE-capable but not delivering (poe_enable: false). There is now a third guard rail for that, returning conflict locally:

$ unifi ports cycle 74:ac:b9:ec:b4:5e 4
{"error":{"kind":"conflict","message":"Port 4 on 74:ac:b9:ec:b4:5e is not currently
 delivering PoE (poe_enable=false), so there is no power to cycle."}}   # exit 6

I should be precise about what that rests on: it is a fact that the command was rejected on a port passing both original checks, and an inference that poe_enable is the controller's precondition — it was the only differing attribute. I could not confirm it by finding a port where a cycle succeeds, for the reason below.

2. It found ports find answering the wrong question. unifi ports find allsky — my own README example — returned conflict, because that name matches two client records: a Pi's wired and wireless interfaces, MACs one bit apart. Only the wired one is on a switch port. The ambiguity check was correct about clients but find is about ports. It now conflicts only when more than one candidate is actually on a port. On this network bedroom substring-matches 13 client records and exactly one is on a port; the old code would have listed all 13.

Verified live

non-PoE port (SFP+)	conflict, exit 6
PoE administratively off	conflict, exit 6
PoE-capable but not delivering	conflict, exit 6
no such port index	not_found, exit 4
piped without --yes	confirmation_required, exit 2
TTY prompt, declined	confirmation_required, exit 2, no request sent
ports find by name / MAC / IP	correct port returned
ports find, nothing on a port	not_found, exit 4
ports list unfiltered	49 ports across the fleet
devices ports <MAC>	bare array, 13 keys, all originals intact

NOT verified live

The successful power-cycle. It is covered by mock-server tests and never fired successfully at a real controller.

The reason is structural, not laziness. I restricted live cycling to a port with nothing attached. But the controller appears to require the port to be actively delivering power — and I swept the whole network: all 11 ports delivering PoE have a live device drawing that power. "Powered but empty" is close to a contradiction, so under that restriction there was no valid target. Bouncing a live device to get a better test result wasn't a trade I was willing to make on someone's home network.

If you have a spare PoE port with a device you don't mind bouncing, that's the one gap worth closing. The mutation path itself is covered by mock-server tests asserting the exact request body, and by tests that assert no HTTP write occurs on each refusal path.

Also not verified live: the genuine ports find conflict (two candidates both on ports). No name on this network currently produces one, so it's covered by a fixture.

Commits

Structured so you can take part of this and leave the rest.

Foundation — the error kind you'd already published, and data the controller was already sending:

• 8250ae0 implement the published conflict error kind
• ee857fc model PoE telemetry and last_connection on PortEntry
• 35e300e make enable/autoneg/is_uplink tri-state in PortEntry
• 324cb71 add power_cycle_port and list_all_device_ports

Read-only commands:

• 10f9e3e add top-level ports list
• 45fb4cc restore link colouring, guard PORTS_LIST, add functional tests
• d7498ac route devices ports through the shared renderer
• b8e91e9 lock in the devices ports bare-array vs ports list envelope split
• fa0aa86 add ports show with full PoE telemetry
• 3419e96 add ports find reverse lookup
• d045f1c show a Connected column in ports find's text output
• ef3e4e1 resolve find ambiguity by port occupancy, not client-name count

The destructive command — these two are separable; take the first and drop the second if you'd rather not have a prompt its siblings lack:

• f319c23 add ports cycle with pre-flight guard rails
• 96dd78d prompt before power-cycling on a TTY

Found by hardware, not by design — the third guard rail exists because the controller rejected a cycle my first two checks allowed:

• d881b34 reject cycling a PoE port not currently delivering power

Tests, docs, cleanup:

• 6dcebf2 cover the cycle() mutation path and cycle_summary
• 9acd530 terminate decline prompt line, widen confirmation_required doc
• 86c0df2 boy-scout cleanup backlog (B1-B8)
• 0e8a53d document the ports command tree
• fb36a0f correct when ports cycle refuses
• 840fabd note that cycle's PoE off-interval is switch-defined
• dfd68cb replace real host names and MACs in test fixtures with generic placeholders

15 files, +2756 / -101.

Not included, on purpose

• --wait to poll poe_power until power returns after a cycle
• the global require_confirmation fix described above
• a module split for src/commands/ports.rs, which grew to ~800 lines. Two reviewers flagged it; I left it because clients.rs is already 759 lines and tui.rs 2989, so it's in line with the repo, and restructuring a file this PR already heavily touches would make the diff harder for you to read. Tracked at ports.rs module split deferred during the ports-command build jaxzin/unifi-cli#1 with a suggested shape if you'd rather have it.
• ports show's text view surfaces 16 of the 25 fields it publishes; -o json carries all 25. Text is the human view, JSON the machine contract. Tracked at ports show: text view surfaces 16 of 25 published fields jaxzin/unifi-cli#2.

Two smaller pre-existing things I noticed but didn't touch, since they're yours to decide: ApiError isn't #[non_exhaustive], so adding a variant is technically breaking for library consumers (making it non-exhaustive is itself breaking, so it's a real fork in the road); and cargo warns on every build about the duplicate unifi / unifi-cli bin targets.

On scope

This is a bigger surface than I'd normally open unannounced, and it's your repo — if you'd rather it were smaller, split across several PRs, spelled differently, or not merged at all, say so and I'll rework it. I'm not attached to the shape, only to the capability.

🤖 Generated with Claude Code