swarmfile-doctor
swarmfile-doctor diagnoses Swarmfile connectivity: DNS, hub, cloud storage, the peer-to-peer network, mDNS, and OIDC - plus install-layout (detects an install an update can't reach) and a plan check. The plan check runs on every machine: it reads your organization's plan standing, and it fails when Swarmfile isn't signed in, because a machine that can't read your plan generally can't reach your files either. On seed/NAS nodes it additionally verifies your plan includes the seeding entitlement. Signed in as a guest reviewer, it passes and says so - guests aren't members, so there's no plan to read. It's a standalone binary - unlike swarmfile doctor, which asks a running engine to run its probe suite, swarmfile-doctor needs no running engine at all. Use it on a machine where the engine isn't up, won't start, or you're not sure which is true.
Flags#
| Flag | Description |
|---|---|
--json | Machine-readable output |
-q, --quiet | Suppress non-error output. Implies --json for stdout. |
--report <path> | Custom path for the JSON report. A report is always written, --json/--repair or not - this only overrides where. Default ~/.cache/swarmfile/last-doctor.json |
--hub-url <url> | Override the hub URL to check |
--no-iroh | Skip the peer-to-peer connectivity probe |
--no-mdns | Skip the mDNS discovery probe |
--iroh-peer <HOST:PORT> | Peer-to-peer network peer to probe against (default 192.0.2.1:4433) |
--cache-dir <path> | Engine cache dir |
-v, --verbose | Verbose output |
--repair | Download the full installer for this platform and run it, replacing every component. |
--yes | Skip the confirmation prompt for --repair |
--repair#
--repair is the most consequential flag here: it downloads the full installer for the current platform and runs it, replacing every Swarmfile component on the machine. It's the headless equivalent of the tray's Diagnostics -> Reinstall button, and it's meant for machines that are broken badly enough that a targeted fix isn't practical - not for routine troubleshooting.
By default --repair stops for a confirmation prompt before it does anything. Pass --yes alongside it to skip that prompt for unattended or scripted repair (for example, a provisioning step that always wants a clean install). See Operations for where repair fits into a broader recovery workflow.
Examples#
Plain diagnostic run:
swarmfile-doctor
JSON output suitable for attaching to a support ticket:
swarmfile-doctor --json --report doctor-report.json
Unattended repair, e.g. from a provisioning script:
swarmfile-doctor --repair --yes