CLI

One executable, nodelets, is the CLI, the bridge service and its installer. nodelets help lists the commands people type.

nodelets <command> [arguments]

Account

Command	What it does
nodelets login	Prints a link and a code, waits for you to approve the code on the dashboard’s Approve CLI access page, and saves the session. Fails if the code expires first or is denied.
nodelets logout	Ends the saved session and removes it from the machine. The bridge is unaffected: it authenticates with its own key.

Bridge

Command	What it does
nodelets bridge status [--json]	Shows the service, the cloud connection, the registration, installed definitions and Things, the paths in use and what to run next. Works while the service is stopped, from a redacted copy of its last status, for administrators.
nodelets bridge register	Enrols this machine’s bridge with the signed-in account, installing and starting the service first if needed. Run it as your own account, not with sudo. Says so if the bridge is already registered.
nodelets bridge recover	Signs in as the owner and gives this bridge a new key under the same bridge ID. On a machine with no bridge identity, asks which of your bridges it replaces. See Recover a bridge.
nodelets bridge start	Starts the service.
nodelets bridge stop	Stops the service.
nodelets bridge restart	Restarts the service.
nodelets bridge uninstall [--purge]	Removes the service and the nodelets executable. --purge also deletes the state directory, with the bridge’s identity and Things.

start, stop, restart and uninstall ask for administrator approval.

Devices

Command	What it does
nodelets definition install FILE [--json]	Sends the definition to the bridge, which checks and installs it with no restart and without contacting a device. Prints Installed definition or Definition is already installed.
nodelets thing list [--json]	Lists the Things on this bridge with their definition, setup state and ID. Does not contact devices.
nodelets thing show ID [--json]	Shows one Thing: definition, setup, base URL or broker, header names, last error and capabilities. Header values are never shown.
nodelets thing add	Asks for a definition, a name, and a base URL with optional headers for HTTP or a broker address for MQTT, then publishes the Thing. The bridge must be connected.
nodelets thing update ID	Asks the same questions and replaces the Thing’s definition and settings. The ID stays.
nodelets thing remove ID	Asks for confirmation, then removes the Thing and its Nodelet. The bridge must be connected.

A Thing’s setup state is active once the cloud has acknowledged it, pending while a change waits for acknowledgement, removing while a removal waits, and removed for a Thing removed since a backup was taken.

Other

Command	What it does
nodelets version [--json]	Shows the build, source digest and platform.
nodelets help	Lists the commands.

Foreground mode

Command	What it does
nodelets bridge run	Runs the bridge in the foreground. The installed service runs this itself.

bridge run takes --state-dir DIR, --socket PATH, and --definition FILE to install a definition as it starts. Set NODELETS_SERVICE_MODE=foreground to keep the control socket inside the state directory, with mode 0600, which suits a container. In foreground mode, bridge start, stop and restart refuse, because the supervisor controls the process. The state directory must persist across restarts: see Keep the state directory.

Output

Output is written for people. A coloured dot shows each state: green healthy, yellow in progress or needing attention, red failed, and a hollow grey dot for a state the CLI could not observe. Failures end with what to do next.

Scripts must use --json where a command offers it, and must not read the human output. Colour appears only on a terminal. It is off when output is piped, when NO_COLOR is set or when TERM=dumb, and FORCE_COLOR turns it on.

Errors go to standard error.

Exit status	Meaning
0	Success
1	The command failed
2	The command was malformed
130	Interrupted

Who can use the bridge

Any local account can open the control socket, and the bridge identifies the account from what the kernel reports about the connection. It accepts root, the service account, and the accounts the installer authorised. Others are told to run the installer as themselves, or to use sudo. Authorised accounts never gain access to the bridge’s key or raw state.

Paths

	Linux	macOS
Executable	/usr/local/bin/nodelets	/usr/local/bin/nodelets
State directory	/var/lib/nodelets	/Library/Application Support/Nodelets/state
Control socket	/run/nodelets/control.sock	/Library/Application Support/Nodelets/run/control.sock
Service	/etc/systemd/system/nodelets.service	/Library/LaunchDaemons/com.nodelets.bridge.plist
Logs	journalctl -u nodelets	/Library/Logs/Nodelets/bridge.log
CLI session	$XDG_CONFIG_HOME/nodelets/session.json, or ~/.config/nodelets/session.json	~/Library/Application Support/nodelets/session.json

Environment variables

Variable	Effect
NODELETS_SERVICE_MODE	native, the default, uses the installed service paths. foreground keeps the socket in the state directory.
NODELETS_STATE_DIR	Overrides the state directory.
NODELETS_SOCKET	Overrides the control socket path.
NODELETS_CLI_CONFIG_DIR	Overrides the directory that holds nodelets/session.json.
NO_COLOR, FORCE_COLOR, TERM	Control colour, as above.