Command line reference
Three commands are installed: mux talks to a running daemon, muxd is the daemon, and swe-mux is the Windows desktop window and tray.
muxd, the daemon
| Flag | What it does |
|---|---|
| --host | Override the configured listener host. Must be a loopback address. |
| --port | Override the configured port for this run. |
| --config | Use a specific configuration file. |
| --dev | Development mode. |
| --local-only | Do not open the direct Tailscale listener for this run. Useful when you are isolating a network problem, because it removes tailnet detection from the startup path. |
| --where | Print where swe-mux is installed, whether its commands are on PATH, and how to run it when they are not. Then exit. |
| --shutdown | Reap every session the PTY supervisor owns, stop the supervisor, and exit. This ends live sessions. It is the deliberate stop-everything command, never part of an update. |
--host takes a loopback address only, because the Tailscale listener is detected rather than configured. Binding a LAN interface is an unsupported configuration rather than a flag that is missing.
mux, the client
| Command | What it does |
|---|---|
| swemux ls | List sessions. Filter with --project, --state, --backend. |
| swemux spawn | Spawn a session. --project is required; --backend, --name, --profile, --exe, and repeatable --arg shape it. |
| swemux send | Send input to a session, named by id, name, or a unique id prefix. |
| swemux kill | Terminate a session. |
| swemux resume | Resume a history entry. --project is required. |
| swemux projects | List Projects. |
| swemux profiles | List launch profiles. |
| swemux harnesses | List every harness in the registry with its detection state. The first thing to run when a CLI you have installed is not being recognised. |
| swemux history | List conversation history. |
| swemux history-duplicates | Report, or with repair merge, history entries that share one conversation. |
| swemux accounts | list, verify, or audit saved provider accounts. |
| swemux doctor | The consolidated read-only diagnostics report. --export prints the full bundle as JSON. |
| swemux update | Report the release check and this install's update path. --install VERSION downloads that release and verifies its hash against the published manifest before anything is staged. |
| swemux reload-daemon | Restart the daemon in place. Sessions survive when the PTY supervisor is on; --force restarts without it and kills every session. |
| swemux install-shortcut | Create the Start Menu and Desktop shortcuts a wheel install structurally cannot (Windows). --startup adds a run-at-login entry, --remove takes them all away. Idempotent. |
Every subcommand takes --json to print the raw daemon response instead of a table, and --url to point at a specific daemon.
Which daemon mux talks to
Resolved in this order, and the order is the contract: --url, then the MUX_URL environment variable, then the configured host and port, then http://127.0.0.1:8765.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. For doctor, a full report with no failing check. |
| 1 | A doctor report with a failing check, local or full. |
| 2 | Usage error. |
| 3 | Daemon unreachable. For doctor, also a clean local report. |
| 4 | Daemon HTTP error. |
| 5 | Ambiguous session name. |
| 6 | Not found. |
A degraded report never exits 0, so a script gating on mux doctor keeps working whether or not a daemon is running. The doctor codes compose the two that already existed rather than adding a scheme of their own.
swemux doctor has two modes, and picks between them itself
- Full reportWhen a daemon answers. Categories for the daemon, each harness, remote access, the firewall, host prerequisites, fleet status health, the background loops, conversation freshness, WSL, and optional assets. Nothing in it reads a secret, a terminal byte, or message content.
- Local reportWhen nothing answers, because a daemon that will not start is the most likely new-user failure and the full report presupposes exactly the thing that is missing. It checks the interpreter, the imports, the config, the frontend bundle, the data directory, the database, the port, this host's pseudoterminal backend, and the supervisor bundle.
The local report marks what it did not check as unchecked rather than folding it into a pass. Folding a skipped check into ok claims health nobody measured, which is worse than the connection error it replaced.