nymea-cli

nymea-cli is a Qt5/Qt6 + FTXUI terminal client for nymead. It connects to the nymea JSON-RPC API over plain TCP or SSL/TLS and renders a fullscreen terminal UI for browsing things, states, params, and actions.

Stack

• Qt5 or Qt6 Core + Network
• FTXUI
• CMake
• Generated Qt/C++ API model from nymea api.json

Current features

• Terminal-only application using QCoreApplication
• Plain TCP and SSL/TLS connections
• nymea default ports:
  • plain TCP: 2223
  • SSL/TLS: 2222
• JSONRPC.Hello handshake with server name, server version, and API version in the header
• Authentication via:
  • stored token
  • interactive username/password form
  • --username / --password
• Persistent connection settings and tokens:
  • /var/lib/nymea/nymea-cli.conf when running as root
  • ~/.config/nymea/nymea-cli.conf otherwise
• TLS fingerprint persistence and warning when the fingerprint changes
• Generated API model from api/api.json
• Thing browser with:
  • thing list
  • thing overview
  • params
  • states
  • actions
• Typed rendering for values:
  • booleans with colored indicator
  • color values with hex text and color swatch
  • compact unit rendering such as ms, °C, %, kWh
• Action execution dialog:
  • browse actions in the thing view
  • inspect action metadata with Space
  • execute actions with Enter
  • bool and allowedValues params use selector-style input

Build

cmake -S . -B build
cmake --build build

To force a specific Qt version, point CMake at that installation explicitly. Examples:

cmake -S . -B build-qt5 -DCMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt5
cmake --build build-qt5

cmake -S . -B build-qt6 -DCMAKE_PREFIX_PATH=/usr/local/Qt/6.10.1/gcc_64
cmake --build build-qt6

Run

./build/nymea-cli

Installed packages also provide:

man nymea-cli

Command line

./build/nymea-cli --help
./build/nymea-cli --version
./build/nymea-cli --host 127.0.0.1 --timeout 5000
./build/nymea-cli --ssl --host 127.0.0.1
./build/nymea-cli --ssl --port 2222
./build/nymea-cli --username admin --password secret

UI navigation

Global:

• q or Esc: quit
• c: reconnect
• h: rerun handshake
• t: refresh things

Main layout:

• Up / Down: move in the focused list
• Left / Right: switch focus between panels

Things view:

• Left panel: thing list
• Right panel: overview, params, states, actions
• Space on a param, state, or action: open metadata inspector
• Enter on an action: open execute dialog

Action dialog:

• Up / Down: select param
• Left / Right / Space: cycle selector values for bool or allowedValues params
• typing: edit free-form params
• Enter: execute action
• Esc: close dialog

Settings file

Connections are stored in INI format and keyed by nymea host UUID. Each connection stores:

• host UUID
• display name
• host
• port
• SSL enabled flag
• auth token
• certificate fingerprint for TLS connections

Stored tokens are reused on reconnect. If the server rejects a token, the token is cleared and login is requested again.

API generation

The pinned schema is stored in api/api.json. The file format is:

• line 1: API version
• remaining content: JSON payload

Regenerate the API model with:

./scripts/generate_nymea_api.py \
  --api-json api/api.json \
  --output src/generated/nymeaapigenerated.h

This writes the stable aggregate entry points src/generated/nymeaapigenerated.h and src/generated/nymeaapigenerated.cpp, plus src/generated/apiutils.* and one header/source pair per generated API class.

Generator rules used by this project:

• generate the exact nymea API object names, aliases, enums, and flags
• prefer value semantics for generated object references
• use indirection only for recursive schema references that require it
• do not hand-edit files in src/generated/

Repository layout

• main.cpp: CLI bootstrap and argument parsing
• src/engine.*: application orchestration, UI state, navigation, action execution
• src/thingmanager.*: thing and thing-class data access helpers on top of the generated API model
• src/nymeajsonrpcclient.*: JSON-RPC socket transport
• src/connectionsettings.*: persistent settings and token storage
• scripts/generate_nymea_api.py: API generator
• src/generated/: generated API model files

Development

Format before finishing changes:

clang-format -i main.cpp src/*.h src/*.cpp

License

This project is licensed under GPL-3.0-or-later. The generated .h and .cpp files carry the same SPDX identifier and warn that manual changes in src/generated/ will be lost the next time the API model is regenerated.