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.

moshctl sends HTTP requests to the MOSH Admin API exposed by

moshbridge

.

The current default API URL is:

http://127.0.0.1:8088

Most commands require a bearer token. The only command intended to work without a token is:

moshctl health

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:

<prespan>mtk_ab12cd_7b2XcYpL9uV3qWmR8nKs4dTfZ1eH6jQa</prespan>

Save it right away.

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>

Unauthenticated health check:

<syntaxhighlight lang=“bash”> moshctl health </syntaxhighlight>

Authenticated status check:

<syntaxhighlight lang=“bash”> moshctl status </syntaxhighlight>

These flags apply to all commands.

Base URL for the MOSH Admin API.

Example:

<syntaxhighlight lang=“bash”> moshctl -url http://192.168.1.50:8088 status </syntaxhighlight>

Path to the raw bearer token file.

Example:

<syntaxhighlight lang=“bash”> moshctl -token-file ~/.config/mosh/token status </syntaxhighlight>

Print the CLI version and exit.

Example:

<syntaxhighlight lang=“bash”> moshctl -version </syntaxhighlight>

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.

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.

Shows the bridge status summary.

Example:

<syntaxhighlight lang=“bash”> moshctl status </syntaxhighlight>

This requires a valid token.

MOSH follows this model:

<pre> Node → Elements → Commands </pre>

Lists all known nodes.

<syntaxhighlight lang=“bash”> moshctl nodes </syntaxhighlight>

Gets details for one node.

<syntaxhighlight lang=“bash”> moshctl node testnode1 </syntaxhighlight>

Lists elements for a node.

<syntaxhighlight lang=“bash”> moshctl elements testnode1 </syntaxhighlight>

Gets details for one element.

<syntaxhighlight lang=“bash”> moshctl element testnode1 relay1 </syntaxhighlight>

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>

Checks the state of a previously queued command.

<syntaxhighlight lang=“bash”> moshctl command-status cmd_123 </syntaxhighlight>

These commands are useful for debugging and bridge inspection.

Shows queue status.

<syntaxhighlight lang=“bash”> moshctl queue </syntaxhighlight>

Shows in-flight command state.

<syntaxhighlight lang=“bash”> moshctl inflight </syntaxhighlight>

Shows recent command failures.

<syntaxhighlight lang=“bash”> moshctl failures </syntaxhighlight>

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.

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.

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>

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>

<syntaxhighlight lang=“bash”> moshctl health moshctl status moshctl nodes moshctl elements testnode1 </syntaxhighlight>

<syntaxhighlight lang=“bash”> moshctl command testnode1 relay1 ON moshctl command-status cmd_123 </syntaxhighlight>

<syntaxhighlight lang=“bash”> moshctl queue moshctl inflight moshctl failures moshctl modules </syntaxhighlight>

<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>

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.