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. It ships on PATH with every desktop install, and - uniquely among these tools - is also published as a standalone download for machines where installing the app isn't an option: Developer ID-signed and notarized on macOS, unsigned on Windows and Linux (so the Windows SmartScreen prompt is expected - see Getting Started); see also Security.
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 (macOS/Linux) or %USERPROFILE%\Swarmfile\last-doctor.json (Windows). |
--hub-url <url> | Override the hub URL to check. Without it, the install's configured hub is used: $SWARMFILE_HUB_URL, else the hub the install's config.json names, else the build's fallback (the hosted hub for a release build). |
--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. Default ~/.cache/swarmfile (macOS/Linux), %LOCALAPPDATA%\swarmfile (Windows). |
-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 |
Exit codes#
The process exit code is the machine-readable verdict, so a script or provisioning step can gate on it without parsing the report:
| Code | Meaning |
|---|---|
0 | Every check passed. |
1 | At least one check failed. |
2 | At least one warn, and no fails. |
--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 Desktop App'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