muxen-synapse-ctl — the operator CLI

muxen-synapse-ctl is how you see what the automations are doing and turn them on and off from a shell. It shows the same information the boat's interface shows, in a terminal.

It talks to the MQTT broker on the synapse/… topics (MQTT interface) and knows nothing about the daemon's internals. It is shipped in the muxen-synapse package at /usr/bin/muxen-synapse-ctl, with bash completion that offers the subcommands and completes instance ids from the retained statuses.

muxen-synapse-ctl [--host H] [--port P] [--json] <command> [args]

Connecting

The broker is resolved in this order:

1. --host / --port
2. $SYNAPSE_MQTT_HOST / $SYNAPSE_MQTT_PORT
3. $MQTT_HOST / $MQTT_PORT
4. 127.0.0.1:1883

Every MQTT subcommand works against any reachable broker, so you can run the tool from a laptop against a boat's broker. journal is the exception: it shells out to journalctl, so it only works on a host running the daemon under systemd — the Brain itself, or over ssh.

--json makes every subcommand emit machine-readable JSON instead of a table.

Commands

Command	What it does
list	Print a table of every automation from its retained synapse/<id> status: ID, ENABLED, RUNNING, VERSION, LAST_RUN, NOTE. Reads retained state — no daemon round-trip.
debug <id> [--what a,b,…]	Request a debug dump, print the reply, then append the last 20 journal lines for <id>. --what selects sections; the default is all of them.
config <id>	Print the instance's effective config — deploy values after validation, plus schema defaults. Read-only.
start <id>	Enable the automation and wait for the republished status. An instance forced off in deploy.json stays disabled and is reported as such.
stop <id>	Disable it. onStop runs, so devices are released.
restart <id>	stop then start, as an explicit cycle so onStop completes before onStart.
journal <id> [-f] [-n N]	The instance's log lines from journalctl -u muxen-synapse, filtered on the [synapse:<id>] tag each line carries. -f follows; -n sets the count (default 50).

Global flags: --host, --port, --json, -h/--help, -V/--version.

Debug sections for --what: fsm, variables, config, state, wiring, commands.

Reading list

$ muxen-synapse-ctl list
ID                       ENABLED  RUNNING  VERSION   LAST_RUN             NOTE
anchor-light             yes      yes      1.0.0     2026-08-16T10:12:03Z
fresh-water-port         yes      yes      1.0.0     2026-08-16T10:09:55Z
watermaker-prompt        yes      yes      1.0.0     2026-08-16T10:11:40Z popup pending
nav-lights               yes      no       1.0.0     2026-08-16T09:58:10Z ERR: pilote state unknown

• ENABLED is the intent — what the deployment and the crew asked for.
• RUNNING is reality — whether the engine currently has it loaded.
• The interesting rows are the ones where the two disagree. enabled=yes running=no means the automation faulted out (see How the engine runs automations) — NOTE carries the reason.
• NOTE shows the last error if there is one, otherwise popup pending if the automation is waiting on the crew.

Because list reads retained topics, it answers instantly and works even when the daemon has just died — in which case the rows are the last state it published. If nothing at all comes back you get no automations (is muxen-synapse running and connected?).

Examples

$ muxen-synapse-ctl config fresh-water-port
{
  "variable": "fresh-water-portside",
  "button": { "deviceId": 0, "index": 3 },
  "lowLevel": 20,
  "action": "off"
}

$ muxen-synapse-ctl debug fresh-water-port --what wiring,commands
{ "id": "fresh-water-port", … "wiring": { "subscriptions": ["app/sensor/fresh-water-portside"],
  "timers": [], "popup": null }, "commands": [ … ] }

--- recent log (journalctl -u muxen-synapse | [synapse:fresh-water-port]) ---
…

$ muxen-synapse-ctl restart fresh-water-port
fresh-water-port: enabled=yes running=yes

$ muxen-synapse-ctl journal fresh-water-port -f     # follow this automation

If start cannot get the automation running you get a hint:

$ muxen-synapse-ctl start nav-lights
nav-lights: enabled=no running=no
  note: still disabled — likely forced off in deploy.json

That is deploy "enabled": false doing its job — a hard force-off cannot be overridden at runtime (Deploying automations).

Exit status

Code	Meaning
0	Success
1	The request timed out (unknown id, or the daemon is down), or start/restart did not reach running, or stop left it running
2	Usage error — unknown command, missing <id>, bad flag
127	journal could not execute journalctl

Timeouts are 2 s to connect, 3 s for a debug reply, 4 s for a start/stop to be reflected in the republished status.