givenergy-cli 1.3.0

Command-line interface to control GivEnergy systems via the local network

GivEnergy CLI

A command-line tool for monitoring and exporting data from GivEnergy inverters over the local network, built on givenergy-modbus.

Requirements

• Python 3.14+
• A GivEnergy inverter accessible on the local network

Installation

uv sync

After uv sync the givenergy-cli command is available at .venv/bin/givenergy-cli, or via uv run givenergy-cli.

Usage

host and port are shared options on the root command. They can also be supplied via the GIVENERGY_HOST / GIVENERGY_PORT environment variables.

tui — interactive terminal UI

uv run givenergy-cli --host 192.168.x.x tui

Live Inverter / Power Flow / Battery panels, a modbus log panel, and a status bar showing connection state and the time of the last refresh. The Inverter panel has collapsible Charge Slot and Discharge Slot sections. The status indicator cycles through Connecting… / Probing… / Reconnecting… / ● Connected / ● Disconnected to show the live transport state; an automatic reconnect is attempted whenever the connection drops.

Key	Action
r	Refresh now (re-reads instantaneous measurements)
Shift+R	Full refresh — also re-reads the holding-register config blocks
l	Toggle the modbus log panel
q	Quit

capture — record wire frames for a bug report

uv run givenergy-cli --host 192.168.x.x capture --output frames.log --duration 60

Connects and records raw redacted Modbus frames for the given duration (default 60 s). Writes one line per frame: a UTC timestamp and the hex payload. The output file is safe to attach to a GitHub issue.

probe — read an arbitrary register range

uv run givenergy-cli --host 192.168.x.x probe --type hr --base 4080 --count 60 --device 0x31

Issues raw Modbus read requests, bypassing the normal capability-driven polling. Useful for exploring undocumented register blocks — e.g. checking whether HR(4080+) holds battery energy totals on AC-coupled models. Requests are split into 60-register chunks automatically; timeouts are reported per-chunk rather than aborting the whole probe.

Option	Description	Default
--type / -t	Register bank: hr (holding) or ir (input)	required
--base / -b	First register address (decimal or 0x-hex)	required
--count / -n	Number of registers to read	60
--device / -d	Modbus device address, decimal or 0x-hex (e.g. 0x11 inverter, 0x31 AC)	0x11

export — dump registers to a portable JSON file

uv run givenergy-cli --host 192.168.x.x export -o plant.json

Connects, runs detect to discover the plant topology, loads the holding-register config, fetches the input registers, and writes every register from every discovered device address. Partial captures are still written on timeout, with a warning.

inspect — render an exported plant

uv run givenergy-cli inspect plant.json

Reconstructs the Plant from the JSON, then prints the Inverter and Battery model fields plus per-device raw register dumps (decimal + hex). No network required.

Environment variables

Variable	Subcommand	Default
GIVENERGY_HOST	all	— (required)
GIVENERGY_PORT	all	8899
GIVENERGY_REFRESH_INTERVAL	tui	15.0
GIVENERGY_LOG_LEVEL	tui	INFO

Project structure

givenergy_cli/
    __init__.py
    __main__.py    — Typer entry point (tui / capture / probe / export / inspect subcommands)
    app.py         — Textual TUI app
    capture.py     — frame-capture logic for bug reports
    registers.py   — export, load, and rich-formatted display of register dumps
tests/
    fixtures/      — anonymised plant JSON fixtures (good + bad-enum cases)

Dependencies

Package	Purpose
givenergy-modbus	Modbus TCP client and data model for GivEnergy inverters
textual	Terminal UI framework
typer	CLI argument parsing
rich	Console formatting for export / capture / inspect output