This is an old revision of the document!
moshctl User Guide
moshctl is the command-line client for the MOSH Admin API. It is the main user-facing tool for checking bridge health, inspecting nodes and elements, and sending commands to devices through moshbridge.
This guide reflects the current CLI behavior in the codebase and the auth flow currently running on the server.
What ''moshctl'' Talks To
moshctl sends HTTP requests to the MOSH Admin API exposed by moshbridge.
The current default API URL is:
Most commands require a bearer token. The only command intended to work without a token is:
moshctl health
Quick Start
1. Create an API Token on the Bridge Host
Run this where moshbridge is installed:
moshbridge admin token --store /var/lib/mosh/adminapi_tokens.json --name moshctl-laptop
This prints a raw token once. It will look something like:
mtk_ab12cd_7b2XcYpL9uV3qWmR8nKs4dTfZ1eH6jQa
Save it right away.
2. Save the Token for ''moshctl''
Recommended, so the token does not end up in your shell history:
echo '<raw-token>' | moshctl auth init --token-stdin
Or explicitly:
moshctl auth init --token '<raw-token>'
By default,
moshctl
stores the token here:
<pre> ~/.config/mosh/token </pre>
If token save and verification succeed, you should see:
<pre> Saved token to /home/youruser/.config/mosh/token Token verified successfully. </pre>
3. Verify Connectivity
Unauthenticated health check:
<syntaxhighlight lang=“bash”> moshctl health </syntaxhighlight>
Authenticated status check:
<syntaxhighlight lang=“bash”> moshctl status </syntaxhighlight>
Global Flags
These flags apply to all commands.
<code>-url</code>
Base URL for the MOSH Admin API.
Example:
<syntaxhighlight lang=“bash”> moshctl -url http://192.168.1.50:8088 status </syntaxhighlight>
<code>-token-file</code>
Path to the raw bearer token file.
Example:
<syntaxhighlight lang=“bash”> moshctl -token-file ~/.config/mosh/token status </syntaxhighlight>
<code>-version</code>
Print the CLI version and exit.
Example:
<syntaxhighlight lang=“bash”> moshctl -version </syntaxhighlight>
Authentication Commands
<code>moshctl auth init</code>
Saves a raw bearer token locally and immediately verifies that it works against the bridge.
Examples:
<syntaxhighlight lang=“bash”> moshctl auth init –token '<raw-token>' </syntaxhighlight>
<syntaxhighlight lang=“bash”> echo '<raw-token>' | moshctl auth init –token-stdin </syntaxhighlight>
With a custom token file:
<syntaxhighlight lang=“bash”> echo '<raw-token>' | moshctl -token-file ~/.config/mosh/lab-token auth init –token-stdin </syntaxhighlight>
Notes:
* The token file stores the raw bearer token, not the bcrypt hash. *
moshctl
writes the token file with restrictive permissions. * The token is verified by making a real API call after saving it.
Health and Status
<code>moshctl health</code>
Checks whether the bridge HTTP API is up.
Example:
<syntaxhighlight lang=“bash”> moshctl health </syntaxhighlight>
Typical response:
<syntaxhighlight lang=“json”> {
"status": "ok"
} </syntaxhighlight>
This is the best first check if you are unsure whether the bridge is reachable.
<code>moshctl status</code>
Shows the bridge status summary.
Example:
<syntaxhighlight lang=“bash”> moshctl status </syntaxhighlight>
This requires a valid token.
Node and Element Inspection
MOSH follows this model:
<pre> Node → Elements → Commands </pre>
<code>moshctl nodes</code>
Lists all known nodes.
<syntaxhighlight lang=“bash”> moshctl nodes </syntaxhighlight>
<code>moshctl node <node_id></code>
Gets details for one node.
<syntaxhighlight lang=“bash”> moshctl node testnode1 </syntaxhighlight>
<code>moshctl elements <node_id></code>
Lists elements for a node.
<syntaxhighlight lang=“bash”> moshctl elements testnode1 </syntaxhighlight>
<code>moshctl element <node_id> <element_id></code>
Gets details for one element.
<syntaxhighlight lang=“bash”> moshctl element testnode1 relay1 </syntaxhighlight>
Sending Commands
<code>moshctl command <node_id> <element_id> <ON|OFF></code>
Sends a command to an element.
Current CLI behavior:
* Command name is always
set
. * Payload is
{"state":"ON"}
or
{"state":"OFF"}
. * Request is sent as
reliable: true
.
Example:
<syntaxhighlight lang=“bash”> moshctl command testnode1 relay1 ON </syntaxhighlight>
Typical response:
<syntaxhighlight lang=“json”> {
"status": "queued", "command_id": "cmd_123", "node_id": "testnode1", "element_id": "relay1"
} </syntaxhighlight>
<code>moshctl command-status <command_id></code>
Checks the state of a previously queued command.
<syntaxhighlight lang=“bash”> moshctl command-status cmd_123 </syntaxhighlight>
Queue, In-Flight, Failures, and Modules
These commands are useful for debugging and bridge inspection.
<code>moshctl queue</code>
Shows queue status.
<syntaxhighlight lang=“bash”> moshctl queue </syntaxhighlight>
<code>moshctl inflight</code>
Shows in-flight command state.
<syntaxhighlight lang=“bash”> moshctl inflight </syntaxhighlight>
<code>moshctl failures</code>
Shows recent command failures.
<syntaxhighlight lang=“bash”> moshctl failures </syntaxhighlight>
<code>moshctl modules</code>
Shows module status.
<syntaxhighlight lang=“bash”> moshctl modules </syntaxhighlight>
Note:
*
queue
,
inflight
, and
failures
currently map to debug-style endpoints and may evolve as the Admin API cleanup continues.
First-Run Troubleshooting
Error: Token File Not Found
You may see:
<pre> Client init error: Read token file “/home/youruser/.config/mosh/token”: open /home/youruser/.config/mosh/token: no such file or directory Hint: create a token with `moshbridge admin token –store /var/lib/mosh/adminapi_tokens.json –name <name>` and save the raw token to /home/youruser/.config/mosh/token </pre>
Fix:
# Create a token with
moshbridge admin token
. # Save it with
moshctl auth init --token-stdin
. # Retry your command.
<code>moshctl health</code> Works, but <code>moshctl status</code> Fails
This usually means:
* the bridge is up * your token is missing, invalid, or revoked
Reinitialize the token:
<syntaxhighlight lang=“bash”> echo '<raw-token>' | moshctl auth init –token-stdin </syntaxhighlight>
Connection Errors
If you see connection failures, check:
*
moshbridge
is running * the API bind address is correct * your
-url
matches the bridge address * the bridge host firewall allows access if you are connecting remotely
Example remote check:
<syntaxhighlight lang=“bash”> moshctl -url http://192.168.1.50:8088 health </syntaxhighlight>
Recommended Daily Workflow
Inspect the Bridge
<syntaxhighlight lang=“bash”> moshctl health moshctl status moshctl nodes moshctl elements testnode1 </syntaxhighlight>
Control a Relay
<syntaxhighlight lang=“bash”> moshctl command testnode1 relay1 ON moshctl command-status cmd_123 </syntaxhighlight>
Check Runtime Issues
<syntaxhighlight lang=“bash”> moshctl queue moshctl inflight moshctl failures moshctl modules </syntaxhighlight>
Command Reference
<pre> moshctl health moshctl status moshctl nodes moshctl node <node_id> moshctl elements <node_id> moshctl element <node_id> <element_id> moshctl command <node_id> <element_id> <ON|OFF> moshctl command-status <command_id> moshctl queue moshctl inflight moshctl failures moshctl modules moshctl auth init –token <raw-token> moshctl auth init –token-stdin </pre>
Mental Model
If you remember just one thing:
moshctl
is a thin local client for the MOSH Admin API. It does not talk directly to radios or devices. It asks
moshbridge
to inspect state and queue commands using the
Node -> Element -> Command
model.