doctor
Diagnose a machine's Solwyn setup — config file, keychain, API readiness, the stored credential, and the bundled API snapshot
doctor runs five local and remote checks and prints one row per result. It is the command to reach for when something else fails unexpectedly, and the one command that still runs when the config file is corrupt. It never mutates anything and never refreshes a token.
solwyn doctor [--mcp [--executable <path>] [--profile read|guardrails]]| Option | Type | Default | Purpose |
|---|---|---|---|
--mcp | boolean | false | Also spawn the MCP server in isolation and check tool discovery and captured-credential reads. |
--executable | path | the installed solwyn | Which installed executable to launch for --mcp. |
--profile | read | guardrails | read | Which MCP tool profile to check. |
--executable and --profile require --mcp; without it they exit 2.
| Contract | |
|---|---|
| Auth | optional — a stored credential enables the authenticated probe |
| Exit codes | 0 every check passed · 1 one or more checks degraded · 2 usage |
| JSON schema | solwyn.doctor.v1; solwyn.doctor.mcp.v1 with --mcp |
doctor always prints its full report, then exits 1 when anything is degraded. A script that assumes a non-zero exit means an error envelope with no payload will misread it. Parse stdout regardless of the exit code.
The five checks
Config. Whether config.toml is absent (defaults apply), loaded, or unreadable. A malformed file is reported without echoing its contents.
Keychain. Whether the OS keychain backend is reachable and whether a stored credential was found. A half-stored JWT pair — one token entry without the other — is reported as degraded.
Readiness. One unauthenticated readiness read against the API, listing each service sub-check. redis, stripe_catalog, and stripe_portal are non-gating: degradation does not fail overall API readiness. A 503 is accepted so a degraded body stays informative. A degraded advisory sub-check alone does not fail doctor when Core reports ready; config, keychain, authenticated-probe and snapshot checks still decide the overall diagnostic result.
Authenticated probe. Skipped when no credential is stored. With a JWT, one identity read. With a project key, one read of the default project's budget — so a project key needs a default_project or the probe is skipped with a note. An invalid credential is reported as degraded; no request is retried and no token is refreshed.
Snapshot. The API contract snapshot bundled in the package must be no more than 30 days old and record a valid upstream commit. This is a drift check on the CLI itself, not on your account.
$ solwyn doctor
Check Status
Overall — One or more diagnostics need attention. degraded
Config — No config file; using defaults. ok
Keychain — Stored credential found. ok
Readiness — HTTP 200; service solwyn-api ready
Readiness db — — ok
Readiness redis — — (non-gating) ok
Readiness stripe_catalog — — (non-gating) ok
Readiness stripe_portal — — (non-gating) ok
Authenticated project_key — A default project is required to test the skipped
project key.
Snapshot — 2026-10-14 (0 days old) ok
Core ref — 4925784d42e18bb6b680e5a87609d1829f1f64a9 okHere the run exits 1 only because the probe was skipped: setting default_project would turn it green.
When the config file is broken
Every other command stops with Could not load configuration. and exit 2 when config.toml cannot be parsed. doctor continues on defaults, marks the API URL as a fallback, and withholds the stored credential — it will not send a keychain secret to a URL it could not confirm. Pass --api-url or set SOLWYN_API_URL to restore the authenticated probe while you repair the file.
Checking the MCP server
doctor --mcp launches the installed solwyn mcp server as an isolated subprocess and verifies the handshake, the advertised tools for the chosen profile, and that a read tool resolves the stored credential correctly. The result lands under solwyn.doctor.mcp.v1. See Agent integration for how to read a failing report.
Related
- Installation —
doctoris the post-install verification step - Configuration — where the file lives and what it may contain
- Authentication — what the keychain and probe checks are looking for