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

''http://127.0.0.1:8088''

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:

<code bash>
moshbridge admin token --store /var/lib/mosh/adminapi_tokens.json --name moshctl-laptop
</code>

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:

<code bash>
echo '<raw-token>' | moshctl auth init --token-stdin
</code>

Or explicitly:

<code bash>
moshctl auth init --token '<raw-token>'
</code>

By default, <code>moshctl</code> 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:

<code bash">
moshctl health
</code>

Authenticated status check:

<code bash>
moshctl status
</code>

== Global Flags ==

These flags apply to all commands.

=== <code>-url</code> ===

Base URL for the MOSH Admin API.

Example:

<code bash>
moshctl -url http://192.168.1.50:8088 status
</code>

=== <code>-token-file</code> ===

Path to the raw bearer token file.

Example:

<code bash>
moshctl -token-file ~/.config/mosh/token status
</code>

=== <code>-version</code> ===

Print the CLI version and exit.

Example:

<code bash>
moshctl -version
</code>

== Authentication Commands ==

===<code>moshctl auth init</code> ===

Saves a raw bearer token locally and immediately verifies that it works against the bridge.

Examples:

<code bash>
moshctl auth init --token '<raw-token>'
</code>

<code bash>
echo '<raw-token>' | moshctl auth init --token-stdin
</code>

With a custom token file:

<code bash>
echo '<raw-token>' | moshctl -token-file ~/.config/mosh/lab-token auth init --token-stdin
</code>

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 &lt;node_id&gt;</code> ===

Gets details for one node.

<syntaxhighlight lang="bash">
moshctl node testnode1
</syntaxhighlight>

=== <code>moshctl elements &lt;node_id&gt;</code> ===

Lists elements for a node.

<syntaxhighlight lang="bash">
moshctl elements testnode1
</syntaxhighlight>

=== <code>moshctl element &lt;node_id&gt; &lt;element_id&gt;</code> ===

Gets details for one element.

<syntaxhighlight lang="bash">
moshctl element testnode1 relay1
</syntaxhighlight>

== Sending Commands ==

=== <code>moshctl command &lt;node_id&gt; &lt;element_id&gt; &lt;ON|OFF&gt;</code> ===

Sends a command to an element.

Current CLI behavior:

* Command name is always <code>set</code>.
* Payload is <code>{"state":"ON"}</code> or <code>{"state":"OFF"}</code>.
* Request is sent as <code>reliable: true</code>.

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 &lt;command_id&gt;</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:

* <code>queue</code>, <code>inflight</code>, and <code>failures</code> 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 <code>moshbridge admin token</code>.
# Save it with <code>moshctl auth init --token-stdin</code>.
# 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:

* <code>moshbridge</code> is running
* the API bind address is correct
* your <code>-url</code> 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:

<code>moshctl</code> is a thin local client for the MOSH Admin API. It does not talk directly to radios or devices. It asks <code>moshbridge</code> to inspect state and queue commands using the <code>Node -&gt; Element -&gt; Command</code> model.