# 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`](https://swarmfile.com/docs/cli/swarmfile), 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](https://swarmfile.com/docs/guides/getting-started#windows-the-smartscreen-prompt)); see also [Security](https://swarmfile.com/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](https://swarmfile.com/docs/admin/operations) for where repair fits into a broader recovery workflow.

## Examples

Plain diagnostic run:

```bash
swarmfile-doctor
```

JSON output suitable for attaching to a support ticket:

```bash
swarmfile-doctor --json --report doctor-report.json
```

Unattended repair, e.g. from a provisioning script:

```bash
swarmfile-doctor --repair --yes
```