Command Reference

Every mlsh subcommand with its flags and a concrete example.

Run mlsh help <command> for the canonical in-binary help.

`mlsh setup`

Bootstraps a node in a cluster. In self-hosted mode, supply both --signal-host and the --token obtained from mlsh-signal cluster create (see deployment).

mlsh setup <cluster> \
  --signal-host <host> \
  --token <CODE>@<UUID>@<FINGERPRINT>

Flag	Description
`<cluster>`	Cluster name (`homelab`, `prod`, …).
`--signal-host <host>`	Hostname of the signal server (self-hosted).
`--token <token>`	Setup token in the form `<CODE>@<UUID>@<FINGERPRINT>`.
`--name <name>`	Override the node name. Defaults to the machine hostname.

Writes ~/.config/mlsh/clusters/<cluster>.toml.

`mlsh adopt`

Enrolls this machine in a cluster using an invite URL.

mlsh adopt "https://signal.example.com/invite?token=XXXX-XXXX" --name nas

Flag	Description
`<url>`	The signed invite URL.
`--name <name>`	Node name for this machine. Defaults to the system username.

`mlsh invite`

Generates a signed invite URL for another machine to join this cluster. Admin-only.

mlsh invite <cluster> --ttl 3600 --role node

Flag	Description
`<cluster>`	Cluster to invite into.
`--ttl <seconds>`	Invite lifetime. Default `3600`.
`--role {admin\|node}`	Role granted on adoption. Default `node`.

Prints a https://…/invite?token=… URL and a terminal QR code.

`mlsh connect`

Activates the overlay tunnel for a cluster.

mlsh connect <name>

Flag	Description
`<name>`	Peer name, or `node.cluster` form (e.g. `homelab` or `nas.homelab`).
`--foreground`	Run the tunnel in the foreground, bypassing the daemon. Useful for debugging.

`mlsh disconnect`

Tears down the overlay tunnel for a peer.

mlsh disconnect <name>

`mlsh status`

Prints the state of all active clusters: overlay IP, uptime, peers, and traffic counters.

mlsh status

`mlsh ui`

Opens the cluster's admin web UI in your default browser. Spawns a localhost proxy that forwards to the control-plane node over the overlay, so the tunnel must be up (mlsh connect <cluster>). Available on control-plane builds.

mlsh ui <cluster>
mlsh ui <cluster> --no-open   # print the URL instead of opening the browser

`mlsh nodes`

Lists all nodes in a cluster with their online/offline status, overlay IP, display name, and client version.

mlsh nodes <cluster>

`mlsh promote`

Changes a node's role in a cluster. Admin-only. The request is routed via the local mlshtund socket to the control-plane node.

mlsh promote <cluster> <node> --role admin

Flag	Description
`<cluster>`	Cluster name.
`<node>`	Node UUID or current display name.
`--role {admin\|node}`	New role.

`mlsh revoke`

Removes a node from a cluster. Admin-only. The revoked node can no longer authenticate to the signal server.

mlsh revoke <cluster> <node>

<node> is the node UUID or its current display name.

`mlsh rename`

Renames a node's display name in a cluster. Admin-only. Renames propagate to overlay DNS in real time.

mlsh rename <cluster> <node> <new-name>

<node> is the node UUID or its current display name. The new name is sanitized for DNS use; see DNS resolution.

`mlsh identity-export`

Exports the node's identity (private Ed25519 key) to stdout for backup.

mlsh identity-export > mlsh-identity.pem

`mlsh identity-import`

Imports a node identity from a PEM file, or from stdin if no file is given.

mlsh identity-import mlsh-identity.pem

`mlsh expose`

Exposes a local service to the public internet over HTTPS by publishing a domain that routes through the signal server's TLS ingress to this node.

mlsh expose <cluster> <target> \
  --domain myapp.<cluster>.example.com \
  --email you@example.com

Flag	Description
`<cluster>`	Cluster name.
`<target>`	Upstream service URL, e.g. `http://localhost:3000`.
`--domain <fqdn>`	Public domain. Must be `*.<cluster>.example.com` (a domain you control, delegated to the signal server).
`--email <addr>`	Contact email for the Let's Encrypt ACME account.
`--acme-staging`	Use Let's Encrypt's staging directory (recommended while testing; production has hard rate limits).

`mlsh unexpose`

Removes a previously exposed service.

mlsh unexpose <cluster> <domain>

`mlsh exposed`

Lists services currently exposed in a cluster.

mlsh exposed <cluster>

`mlsh tunnel`

Manages the overlay tunnel daemon (mlshtund) as a system service.

macOS: LaunchDaemon at /Library/LaunchDaemons/io.mlsh.tund.plist.
Linux: systemd unit at /etc/systemd/system/mlshtund.service.

mlsh tunnel install --auto-connect homelab,prod
mlsh tunnel uninstall
mlsh tunnel status

Subcommand	Description
`install`	Install `mlshtund` as a system daemon. `--auto-connect <list>` auto-connects the listed clusters on daemon start.
`uninstall`	Uninstall the daemon.
`status`	Show daemon installation status.

Persisted clusters are also auto-reconnected when the daemon itself starts — --auto-connect is only needed if you want the daemon installed and a specific set of clusters connected on boot.

`mlsh control`

Manages the control-plane role on this node. The control-plane node hosts the admin REST API, the web UI, and the authoritative store of users, nodes, and display names. Exactly one node per cluster carries the control role. Available on control-plane builds.

mlsh control promote <cluster>
mlsh control demote  <cluster>
mlsh control migrate <cluster> <target-node>

Subcommand	Description
`promote`	Start `mlsh-control` on this node and add the `control` role to its cluster config.
`demote`	Stop `mlsh-control` and remove the `control` role.
`migrate`	Demote this node and print the manual steps to bring up the target node as the new control node. Peer-to-peer data transfer is not yet automated.

See config file for the on-disk format stored in ~/.config/mlsh/.

Edit this page on GitHub