Skip to content

cli.md

Latest commit

 

History

History
132 lines (108 loc) · 7.09 KB

cli.md

File metadata and controls

132 lines (108 loc) · 7.09 KB
Raw

The muster CLI

cmd/muster is a machine client for muster's JSON API, used by agents, scripts and you. It builds as the muster binary.

Verbs

The verb set is pinned in two places:

  • tests/verb-ledger.sh, run by make verb-ledger, interrogates the built binary;
  • cmd/muster/tree_test.go walks the command tree.
group verbs
tasks task ls, task get, task create, task comment, task status
an agent's own task agent task get, agent task comment, agent task status
agents agent ls, agent messages, agent resolve, chief ask, chief replace (replacing the chief)
browser flows flow enqueue, flow ls, flow status, flow cancel
credentials token ls, token revoke, whoami
session routing route reply (a mirrored session's answer to a routed message)
plugins plugins retry <message-id> (retry an unconfirmed message)
setup doctor (below)

Global flags: --api-url, --token, --env-file (default ~/.muster/muster.env) and --timeout.

Configuration

The CLI looks for each setting in three places, from lowest to highest priority:

  1. the env file;
  2. the environment;
  3. flags.
setting variable flag
API URL (no default; it must be an absolute http(s) URL) MUSTER_API_URL --api-url
credential MUSTER_TOKEN (older name: MUSTER_HOOK_TOKEN; MUSTER_TOKEN wins within one source) --token

The usual credential is a personal API token (mst_…). Mint it in the browser at /account/tokens; it acts as you (auth.md). Tokens cannot be minted from the CLI. muster token ls and muster token revoke <id> manage them, and muster whoami says who a credential acts as.

Installing it from elsewhere

This repository is public, so the CLI can be fetched and pinned by revision. In a downstream flake, add muster.url = "github:ZacxDev/muster" and use muster.packages.${system}.muster-cli.

  • The output is muster-cli, and the binary is muster. The output is not named muster, because that name belongs to the service.
  • The binary answers to whatever name you invoke it as. It uses argv[0] for its help text, its error prefix and its version-skew note. So you can symlink it under another name, and nothing else changes.
nix run github:ZacxDev/muster#muster-cli -- task ls
go build -o muster ./cmd/muster         # or plain Go

muster doctor

Checks a muster installation end to end from the machine it runs on, and prints how to fix each failure. INSTALL.md ends with it.

muster doctor --deploy-env ~/muster/.env    # on the machine running the server
muster doctor --api-url https://<your-muster-address>   # on any other machine

On a machine other than the server, the doctor needs the server's address: --api-url, or MUSTER_API_URL in the environment or in the env file. The API URL has no default, so without one the doctor stops before checking anything. INSTALL.md's Step 10 passes --api-url there.

check PASS means read from
server GET /health answers muster's document, over https the server
manifest /manifest.webmanifest is a standalone manifest with icons the server
hook-token the server enforces a hook token and accepts this one GET /api/doctor
mirror-hosts every host holding a live mirror token is connected GET /api/doctor (the tunnel hub)
this-host the server accepts THIS machine's mirror token and holds a connection from it GET /mirror/host, with the token muster-mirror's settings file names
mirror-service the muster-mirror user service is active here systemctl --user is-active (Linux), launchctl print (macOS)
tmux tmux is installed here tmux -V
sign-in the operator password signs in, and the session opens the board POST /login, then GET /tasks
push the VAPID keys are set GET /api/push/vapid-public-key (signed in), else GET /api/doctor
dictation a bundled 1.7 s spoken sample comes back as text through POST /transcribe the server and its speech-to-text service
  • Exit status: 0 when no check FAILs, 1 when any does. A SKIP (a check that cannot be made from this machine, or --skip) never fails the run.
  • Output: the report and the QR code go to stderr; stdout is one JSON document, {"url", "ok", "checks": [{"name", "status", "detail", "fix"}]}, as for every other verb, wherever the two streams go. To read only the report (a terminal, or an agent whose shell merges the streams), send stdout away: muster doctor >/dev/null. INSTALL.md's Step 10 does.
  • Credentials: the server-side checks need a token (the hook token, or a personal token; a personal token sees only its owner's hosts); without one they SKIP. --deploy-env reads the compose .env: its MUSTER_PUBLIC_URL and MUSTER_HOOK_TOKEN beat the env file and the environment (only --api-url / --token beat them), and its MUSTER_UI_PASSWORD is used for the sign-in, push and dictation checks. 🔴 The password is sent only to that file's MUSTER_PUBLIC_URL; pointed at any other server, sign-in SKIPs.
  • this-host reads muster-mirror's settings file (--mirror-env, default ~/.config/muster-mirror/env) for its token file and its MUSTER_MIRROR_URL, and asks THAT server with the token. 🔴 The token is never sent anywhere else: when doctor is checking a different URL, this check SKIPs and names the mirror's server. A refused token is a FAIL; so is a connection under this host's name made with another token (two machines minted under one name). It SKIPs on a machine with no settings file.
  • Flags: --skip <check>[,<check>…], --mirror-env, --mirror-unit (default muster-mirror.service), --mirror-label (default io.github.zacxdev.muster-mirror).
  • The QR code of the URL is drawn with qrencode when it is installed; the URL is printed either way.
  • GET /api/doctor is behind the armed hook token: a server with no MUSTER_HOOK_TOKEN answers 503 with "unarmed": true, which is what the hook-token check reports.

Other binaries

binary what it is
muster-server The service. Subcommands: mirror token create <host>, mirror token ls, mirror token revoke <id>, vapid generate, invite --claim-admin, user disable <id>, user enable <id>.
muster-migrate Applies the schema to DATABASE_URL. The server also migrates itself at boot. --rls-off and --rls-on are the row-level-security rollback tools (schema.md).
muster-mirror The host agent for mirrored sessions.
ccd The supervisor inside the claude-code agent image (provisioner.md).

The container image (Dockerfile) ships /muster-server, /muster-migrate and /agent-cli/muster. The flake builds muster-cli, muster-migrate, muster-mirror and a migrator image (migrate-image).