powerz CLI reference
1. Build and connect
# macOS
brew install libusb pkgconf
# Debian/Ubuntu
sudo apt install libusb-1.0-0-dev pkg-config
go install github.com/ljagiello/gopower-z/cmd/powerz@latest
Connect the meter's USB-C port marked HID to the computer. Plug the source (charger) into the meter's female receptacle and the device under test onto its male plug. On macOS no driver or root is needed. On Linux, the in-kernel powerz hwmon driver owns the interface; powerz detaches it while running, and you need a udev rule granting access to 5fc9:0063 (otherwise exit code 6). Linux is built and unit-tested in CI but has not yet been run with a meter attached.
2. Quick start
powerz # dashboard on a terminal, one JSON reading when piped
powerz read # one snapshot
powerz measure --duration 10s # min/mean/max, energy, charge, USB-PD capture
powerz info # model, firmware, serial, settings
powerz pd --duration 30s # decoded USB-PD traffic, then a summary line
powerz log --duration 1m --interval 500ms --format csv > run.csv
powerz schema # the machine-readable reference
3. Agent contract
- JSON whenever stdout is not a terminal (force it with
--json, or text with--text). stdout carries data only; diagnostics and errors go to stderr. - Fixed shapes. Every documented key is always present. Unavailable values are
nulland empty lists are[]. Every object carriesschema_version(currently1). - Units are in field names:
_v,_a,_w,_wh,_mah,_c,_s,_ms,_uv,_ua,_sps,_percent. - Timestamps are UTC ISO 8601 with milliseconds:
2026-11-17T01:34:25.627Z. - Direction. Current and power are positive when flowing from the meter's female receptacle to its male plug, which is the normal set-up and matches the meter's screen.
directionsays so explicitly (receptacle_to_plug,plug_to_receptacleornone), andraw.ibus_uakeeps the meter's own signed value. - Errors are one JSON object on stderr with
code,exit_code,retryableand an actionablehint. - A non-zero exit can still carry data.
measureprints its object andpdits summary line when they end early: on SIGINT/SIGTERM (exit 130,"end_reason":"interrupted", which is what an agent harness timeout sends) or when the meter disappears, is taken by another program or cannot be drained (exit 3, 4 or 1,"end_reason":"error").loglines already printed stay valid. Read stdout before discarding it. - Bounded.
read,measure,info,devicesandschematerminate on their own.logandpdtake--duration, which automation should always set. - One process per meter. A concurrent call fails with
busy(exit 4, retryable) unless it passes--wait 10sto queue. - Validation, not silent changes. Out-of-range values such as
--interval 5msare usage errors that state the limit. - Interpretations are separate. Fields under
inferredare computed by powerz, not reported by the meter. - Unknown is not the same as empty. Firmware-dependent fields are decoded only for firmware 1.7.9 to 2.0.7, the versions that were analysed. For any other firmware, or when the version cannot be read (
firmware_errorsays why), they arenull,raw.tail_layoutisunknownandinferred.dashboard_classifierisnull. Anulldashboard label with a non-null classifier means the screen shows [N/A].
4. Commands
| Command | Output | Flags | Purpose |
|---|---|---|---|
read | one JSON object | - | One snapshot. Default command when stdout is not a terminal. Reads the firmware version first (CONNECT plus one MemoryRead) to decode the firmware-dependent fields. |
measure | one JSON object | --duration 5s --interval 100ms (≥ 20 ms) --pd=true | Samples for a fixed time. Returns stats (min/mean/max/last of V, A, W, °C), energy and charge over integrated_s, the dominant direction, and the USB-PD capture with every record. end_reason says whether the window completed or ended early. The main command for agents. |
log | JSON lines or CSV | --interval 200ms (≥ 20 ms) --format jsonl|csv --count/-n --duration | Streams snapshots (same shape as read). CSV columns: time, vbus_v, ibus_a, power_w, direction, vbus_avg_v, ibus_avg_a, power_avg_w, temp_c, cc1_v, cc2_v, dp_v, dm_v, vdd_v. |
pd | JSON lines | --interval 25ms (≥ 10 ms) --duration --count/-n --goodcrc | One record per captured USB-PD message or event, then a final "kind":"summary" line with counts, capabilities, contract, end_reason and a note when nothing was captured. Bytes the meter delivered that cannot be parsed are kept as "kind":"undecoded" records. Sends only GET_DATA for the PD buffer: no session and no memory reads. |
info | one JSON object | - | USB descriptors; model, firmware and hardware versions (ISO dates), serial and UUID; settings (sample rate, name, brightness, raw codes). The identity comes from three memory blocks: a block that cannot be read leaves only its fields null and is listed in errors (exit 7). |
devices | one JSON object | - | Lists connected meters without claiming them, so it works while another process holds the meter. |
watch | terminal UI | --interval 200ms --no-pd | Live dashboard for humans; refuses to run without a terminal. |
schema | one JSON object | - | Commands, flags with types and defaults, typed field definitions with nullability, exit codes, verified facts and caveats. |
version | one JSON object | - | Tool and schema version (also --version). |
completion | shell script | bash|zsh|fish|powershell | Shell completion for commands and flags. |
help | text | - | Usage of powerz or of one command (also --help on any command). |
Common flags, accepted before or after the command: --json --text --serial S --timeout D (≥ 100 ms) --wait D --trace. Flags take two dashes (--duration 10s or --duration=10s); -n for --count is the only shorthand. A single-dash long flag such as -duration is a usage error whose hint says so.
5. Output examples
All captured live from a KM003C on firmware 1.9.5 powering a test board at about 0.13 A.
powerz read
{
"schema_version": 1, "time": "2026-11-17T01:34:25.627Z", "serial": "050002",
"firmware_version": "1.9.5", "firmware_error": null,
"vbus_v": 5.076484, "ibus_a": 0.132566, "power_w": 0.672969, "direction": "receptacle_to_plug",
"vbus_avg_v": 5.076229, "ibus_avg_a": 0.132723, "power_avg_w": 0.673732,
"temp_c": 27.906, "temp2_c": null,
"cc1_v": 0.0003, "cc2_v": 1.6264, "dp_v": 2.9827, "dm_v": 0.0023, "vdd_v": 3.2049,
"cc2_avg_v": 1.624, "dp_avg_v": 2.982, "dm_avg_v": 0.002,
"sample_rate_sps": 50, "sink_battery_percent": null,
"inferred": {
"dashboard_label": null, "dashboard_label_2": "VOOC", "dashboard_classifier": "1.9.5",
"cc": {"attached": "cc2", "advertisement": "3.0A", "advertised_current_a": 3,
"text": "Type-C attached on CC2, source advertises 3.0A"}
},
"raw": {"ibus_ua": -132566, "vbus_uncal_avg_uv": 5077284, "ibus_uncal_avg_ua": -132767,
"tail_layout": "line-averages", "tail_hex": "00 80 5A 06 A6 0B 02 00", "accel_status": null}
}
dashboard_label / dashboard_label_2 reproduce the two protocol lines on the meter's screen (here [N/A] and VOOC) using the meter firmware's own algorithm, named by dashboard_classifier. They describe the D+/D− voltage signature, not a confirmed protocol session. When the classifier is null (unknown or unanalysed firmware) the labels are unknown, not [N/A].
powerz measure --duration 2s
{
"schema_version": 1, "serial": "050002", "firmware_version": "1.9.5", "firmware_error": null,
"start": "2026-11-17T01:35:07.564Z", "end": "2026-11-17T01:35:09.565Z", "end_reason": "completed",
"duration_s": 2, "integrated_s": 2, "interval_s": 0.1,
"samples": 20, "failed_samples": 0, "last_error": null, "direction": "receptacle_to_plug",
"stats": {
"vbus_v": {"min": 5.075507, "mean": 5.076038, "max": 5.076464, "last": 5.076093},
"ibus_a": {"min": 0.131757, "mean": 0.134602, "max": 0.140898, "last": 0.134642},
"power_w": {"min": 0.668811, "mean": 0.683243, "max": 0.715156, "last": 0.683455},
"temp_c": {"min": 27.891, "mean": 27.907, "max": 27.914, "last": 27.906}
},
"energy_wh": 0.000379607, "charge_mah": 0.074784,
"last": { …same shape as read… },
"pd": {
"messages": 0, "events": 0, "undecoded": 0, "source_capabilities": [], "last_request": null, "contract": null,
"note": "no USB-PD activity was captured in this window; this is normal when nothing was connected or renegotiated (…) - reconnect the device during the capture to observe it",
"records": []
}
}
powerz info
{
"schema_version": 1,
"usb": {"manufacturer": "ChargerLab", "product": "POWER-Z KM003C", "serial": "050002", "bus": 2, "address": 20},
"device": {"model": "KM003C", "firmware_version": "1.9.5", "firmware_date": "2025-01-07",
"hardware_version": "2.2", "hardware_date": "2024-09-23", "serial": "050002",
"uuid": "0123456789ABCDEF0123456789ABCDEF", "adc_tail_layout": "line-averages"},
"settings": {"device_name": "POWER-Z", "sample_rate_sps": 50, "brightness_percent": 49, "rotation_code": 2,
"auto_rotate": true, "language_code": 1, "theme_code": 0, "checksum_ok": true},
"errors": []
}
powerz pd --duration 20s
One line per record, then a summary. PD records keep a fixed shape too: message fields are null on events and the other way round. A record looks like this:
{"schema_version":1,"time":"…","meter_time_ms":10000,"kind":"message","sop":"SOP","message":"Source_Capabilities",
"class":"data","power_role":"source","data_role":"dfp","spec_revision":"3.x","message_id":0,"from_meter":false,
"objects_hex":["0001912C","0002D12C"],
"source_capabilities":[{"index":1,"type":"fixed","min_voltage_v":5,"max_voltage_v":5,"max_current_a":3,
"max_current_20v_a":null,"max_power_w":15,"raw_hex":"0001912C","text":"Fixed 5.00V 3.00A (15.0W)"}, …],
"request":null,"event":null,"cc_line":null,"param":null,"raw_hex":"…"}
{"schema_version":1,"kind":"summary","time":"…","end_reason":"completed","duration_s":20,"messages":0,"events":2,
"undecoded":0,"source_capabilities":[],"last_request":null,"contract":null,
"note":"the device was attached/detached during the capture (see events) but no USB-PD messages were exchanged: …"}
The record above is illustrative: no PD negotiation has been captured live yet. The summary line has the shape of real output. When measure or pd is stopped early, the same objects are printed with "end_reason":"interrupted" (exit 130) or "error" (the error's exit code).
6. Errors and exit codes
{"schema_version":1,"error":{"code":"busy","exit_code":4,"message":"km003c: meter is in use by another program (…)",
"retryable":true,"hint":"another program holds the meter (…); retry, or pass --wait 10s to queue behind it"}}
{"schema_version":1,"error":{"code":"usage","exit_code":2,"message":"unknown command \"mesure\"",
"retryable":false,"hint":"did you mean `powerz measure`? commands: devices, help, info, log, measure, pd, read, schema, version, watch"}}
| exit_code | code | Retryable | Meaning |
|---|---|---|---|
| 0 | - | - | Success |
| 1 | error | no | I/O or protocol failure |
| 2 | usage | no | Unknown command, bad flag or value (the hint lists valid flags and formats) |
| 3 | not_found | no | No meter connected (or none with --serial; the message lists connected serials). If the meter disappeared mid-run, measure/pd printed what they had (end_reason error) |
| 4 | busy | yes | Another process holds the meter; use --wait. If it was taken mid-run, measure/pd printed what they had |
| 5 | timeout | yes | The meter did not answer in time |
| 6 | permission_denied | no | The OS denied USB access (Linux udev) |
| 7 | partial | yes | stdout JSON is valid but incomplete (failed_samples > 0, or info.errors not empty) |
| 130 | interrupted | no | SIGINT / SIGTERM; measure and pd printed what they had collected (end_reason interrupted) |
7. Agent recipes
How much power does the attached device draw?
powerz measure --duration 30s --wait 10s
# .stats.power_w.mean / .max (peak draw), .energy_wh over .integrated_s, .direction
What does this charger offer, and what did the device negotiate?
USB-PD is only exchanged when the device attaches or renegotiates, so start the capture first and connect the device during it:
powerz measure --duration 20s
# .pd.source_capabilities[] offered PDOs (fixed/PPS/AVS: volts, amps, watts)
# .pd.contract the Request the source accepted and confirmed with PS_RDY
# .pd.note set when nothing was captured
# .last.inferred.dashboard_label* the meter's D+/D- protocol labels
Handling failures
- Exit 4 or 5: retry; pass
--wait 10sto avoid exit 4. - Exit 3: ask the human to connect the meter (data port to the computer).
- Exit 7: the JSON on stdout is valid; check
failed_samples,last_errororerrors. - Exit 130, 3, 4 or 1 from
measureorpd: stdout may still hold a result for the part of the window that was captured;end_reasontells. - Never run two powerz commands against one meter in parallel.
8. Safety model
Every frame is checked against a whitelist (hardware/km003c/guard.go) right before it goes to the device. A fuzz test proves the whitelist accepts exactly these frames and nothing else:
GET_DATAfor ADC, settings and the PD buffer (powerz uses only the vendor bulk interface; the HID and CDC interfaces are never opened);CONNECTandDISCONNECT;MemoryReadof exactly three fixed 64-byte information blocks.
Never sent: settings writes, factory reset, firmware/DFU commands, authentication, stream control, and the CDC text commands that make a charger raise VBUS. powerz cannot change the voltage on the bus. Ending each session with DISCONNECT means the meter does not queue an unsolicited frame for the next program.
9. Verified and caveats
- Verified on firmware 1.9.5 under a 0.44 A load: VBUS, current, power, CC and D+/D− match the meter's screen. Positive current means receptacle → plug, and the screen's arrow agrees. The dashboard labels (
[N/A]/VOOC) match the screen. - USB-PD decoding follows the USB-PD 3.1 specification and is fuzzed, but has not yet been checked against a live negotiation.
- Sniffed protocol sessions (AFC/FCP/SCP/UFCS/VOOC sessions the meter detects) live only in firmware RAM and are not exposed over USB.
- Polling rate: the meter samples at its configured rate (see
info); polling faster repeats values. - PD buffer: reading PD drains the meter's buffer, so only one consumer sees each record.
- Firmware newer than 2.0.7 is not guessed: its firmware-dependent fields and dashboard labels are reported as unknown until that firmware has been analysed.