NYMEA-CLI(1)

NAME
nymea-cli - fullscreen terminal client for nymead

SYNOPSIS
nymea-cli [-H host] [-s] [-p port] [-t milliseconds] [-u username] [-w password] [--help] [--version]

DESCRIPTION
nymea-cli is a terminal-only Qt5/Qt6 + FTXUI client for nymead. It connects to the nymea newline-delimited JSON-RPC interface over plain TCP or SSL/TLS and presents a keyboard-driven fullscreen interface for browsing things, inspecting metadata, configuring devices, exploring the API model, and executing server-side actions.

At startup the client performs JSONRPC.Hello, shows the server name, server version, and API version in the header, and then authenticates with a stored token or with username/password credentials. Tokens are persisted per saved connection and reused across restarts. If a stored token is rejected, it is cleared and authentication is requested again.

The default nymea ports are 2223 for plain TCP and 2222 for SSL/TLS. When TLS is enabled, the server certificate fingerprint is stored per connection and a warning is shown if it changes.

OPTIONS

-H, --host host
    Connect to the specified nymead host. The default is 127.0.0.1.

-s, --ssl
    Use SSL/TLS via QSslSocket. This changes the default port to 2222.

-p, --port port
    Connect to the specified TCP port. If omitted, the default is 2222 when --ssl is set and 2223 otherwise.

-t, --timeout milliseconds
    Set the timeout in milliseconds for connection and reply waits. The default is 5000. The value must be greater than zero.

-u, --username username
    Username to use for JSONRPC.Authenticate. If authentication is required and a stored token is unavailable or rejected, the client attempts automatic login with this value.

-w, --password password
    Password to use for JSONRPC.Authenticate.

--help
    Show command line help and exit.

--version
    Show the program version and exit.

INTERFACE

  Main Views
The main menu provides access to the things browser, thing configuration flows, the API browser, settings, logout, and an about screen.

The things view contains a search field, a filtered thing list, and a details pane with overview, parameters, states, and actions. The configuration view is used for setup, rename, and remove flows. The API browser exposes methods, notifications, types, enums, and references from the generated nymea API model.

  Global Keys

q   Quit the application.

Esc Quit the application, close the help screen, or close the active dialog, depending on the current context.

h, ?
    Open the help screen.

c   Reconnect to the current server.

t   Refresh things from the server.

Up / Down
    Move the selection in the focused list.

Left / Right
    Switch panels or move between subviews.

Enter
    Activate the selected item.

Space
    Toggle the thing inspector when supported by the active view.

  Things View

s   Cycle the thing sort mode.

f   Cycle the thing category filter.

Left / Right
    Switch between search, thing list, and details.

Space
    Open or close the inspector for the selected parameter, state, or action.

Enter
    Open the selected action or follow the selected setup flow.

  Configure Things

Up / Down
    Move between menu entries or list rows.

Enter
    Open the selected setup, rename, or remove flow.

Typing
    Filter available thing classes in search fields.

  Settings

Up / Down
    Select server info, time zone, update, shutdown, restart, or reboot.

Right, Enter
    Open the details pane or apply the selected action, depending on the current row.

Typing
    Filter time zones in the time zone view.

  API Browser

Typing
    Filter methods, notifications, types, and enums.

Backspace
    Remove the last filter character.

Left
    Go back in API browser history.

Right
    Move between search, list, and references panes.

Enter
    Follow the selected referenced type.

  Dialogs

Action dialog
    Use Up / Down to choose a parameter. Use Left / Right or Space for boolean and allowed-values selectors. Press Enter to execute or Esc to close.

Login dialog
    Press Enter to submit credentials. Esc quits the application.

Confirmation dialogs
    Press Enter to confirm and Esc to cancel.

FILES

/var/lib/nymea/nymea-cli.conf
    Settings file used when running as root.

~/.config/nymea/nymea-cli.conf
    Settings file used for non-root users.

Saved connections are keyed by nymea host UUID. Each entry stores the display name, host, port, SSL flag, authentication token, and TLS fingerprint.

EXAMPLES

Connect to a local nymea instance using the default plain TCP port:

        nymea-cli

Connect to a remote host with TLS and the default TLS port:

        nymea-cli --ssl --host nymea.example.org

Use a custom timeout and explicit TCP port:

        nymea-cli --host 192.0.2.10 --port 2224 --timeout 10000

Authenticate with explicit credentials:

        nymea-cli --host 192.0.2.10 --username admin --password secret

EXIT STATUS

0   Success.

1   Invalid command line arguments or application failure.

SECURITY
Passing a password on the command line can expose it to other local users through process listings or shell history. Prefer interactive authentication when possible.

When a stored TLS fingerprint changes, nymea-cli shows a warning before continuing to use the connection.

LICENSE
This project is licensed under GPL-3.0-or-later.

SEE ALSO
nymead(8)