SOLWYN
Commands

doctor

Diagnose a machine's Solwyn setup. Config file, credential store, 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.

Terminal
solwyn doctor [--mcp [--executable <path>] [--profile read|guardrails]]
OptionTypeDefaultPurpose
--mcpbooleanfalseAlso spawn the MCP server in isolation and check tool discovery and captured-credential reads.
--executablepaththe installed solwynWhich installed executable to launch for --mcp.
--profileread | guardrailsreadWhich MCP tool profile to check.

--executable and --profile require --mcp; without it they exit 2.

Contract
Authoptional; a login or API key enables the authenticated probe
Exit codes0 every check passed · 1 one or more checks degraded · 2 usage
JSON schemasolwyn.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.

Credential store. Which store is in use (the keychain or the credentials file, with its path), whether it is reachable, and whether a stored credential was found. An unavailable store is an error. An incomplete login, an unreadable login, or an expired login is reported as degraded, with a hint to run solwyn login. When the keychain is in use but the credentials file still holds credentials for this API, the detail adds that the file is not in use and suggests solwyn logout to clear both stores. JSON reports this check as credential_store; before 0.4.0 it was keychain.

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, credential-store, authenticated-probe and snapshot checks still decide the overall diagnostic result.

Authenticated probe. Skipped when no credential is stored. With a login, one identity read. With an API key, one read of the selected project's budget, so an API key needs a project (--project, SOLWYN_PROJECT or .solwyn.env) or the probe is skipped with a note. An invalid credential is reported as degraded, and no request is retried.

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.

Terminal
$ solwyn doctor
Check                                                                     Status
Overall — One or more diagnostics need attention.                       degraded
Config — No config file; using defaults.                                      ok
Credentials: Stored credential found in file (/home/alice/.local/share/solwyn/credentials.json).  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
API key.
Snapshot — 2026-10-14 (0 days old)                                            ok
Core ref — 4925784d42e18bb6b680e5a87609d1829f1f64a9                           ok

Here the run exits 1 only because the probe was skipped: naming a project with SOLWYN_PROJECT or .solwyn.env 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 stored 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. With an API key, its key_project check asks Solwyn which project the key resolves to for the launch project and reports the project's name, id and mode and the key's expiry, or the refusal code. The result lands under solwyn.doctor.mcp.v1. See Agent integration for how to read a failing report.

  • Installation — doctor is the post-install verification step
  • Configuration — where the file lives and what it may contain
  • Scoped login: what the credential store and probe checks are looking for

On this page