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 <code>moshctl</code> Talks To
moshctl
sends HTTP requests to the MOSH Admin API exposed by
moshbridge
.
The current default API URL is:
<pre> http://127.0.0.1:8088 </pre>
Most commands require a bearer token. The only command intended to work without a token is:
<pre> moshctl health </pre>
Quick Start
1. Create an API Token on the Bridge Host
Run this where
moshbridge
is installed:
<syntaxhighlight lang=“bash”> moshbridge admin token –store /var/lib/mosh/adminapi_tokens.json –name moshctl-laptop </syntaxhighlight>
This prints a raw token once. It will look something like:
<pre> mtk_ab12cd_7b2XcYpL9uV3qWmR8nKs4dTfZ1eH6jQa </pre>
Save it right away.
2. Save the Token for <code>moshctl</code>
Recommended, so the token does not end up in your shell history:
<syntaxhighlight lang=“bash”> echo '<raw-token>' | moshctl auth init –token-stdin </syntaxhighlight>
Or explicitly:
<syntaxhighlight lang=“bash”> moshctl auth init –token '<raw-token>' </syntaxhighlight>
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.