CLI reference: sparkwing doctor
CLI reference: sparkwing doctor
Every sparkwing doctor command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in cli-reference.md.
sparkwing doctor
Inspect and repair abandoned local state
Inspects local state and repairs entries whose owners have stopped. --dry-run reports proposed repairs. The command preserves live processes, active daemon state, and cluster-scoped records.
Repairs cover home permissions, abandoned local run records, abandoned box-slot locks, ended local concurrency records, and orphaned run directories. Run-record repair requires a reachable daemon so held runs remain protected. A held box-slot lock is reported with guidance to update the pipeline SDK.
Run-directory removal requires a local store with recorded runs and profiles that all use that store. Directories written within the grace period remain. Unaccounted directories are reported for inspection.
On POSIX systems, permission repair removes group, other, and special bits while retaining existing owner access. The walk preserves symlinks without following them. Windows access permissions are reported as unverified.
The report includes daemon reachability, repeated admission rejections, version mismatches, quarantined ledgers, and capacity measurement problems. It names the reset command for excessive learned demand floors.
Standalone stores are listed with run counts and the oldest run's age. Inspect their records before deleting a store directory.
--timeout bounds the daemon and local-state checks, each taking a slice of it, so a daemon that accepts connections and answers nothing is reported as wedged rather than spending the whole budget. Recovering a wedged daemon means stopping the process holding its socket; a restart needs a handshake it will not answer. When the budget runs out mid-sweep, doctor prints what it reached alongside the error.
Flags
| Flag | Description |
|---|---|
--dry-run | Report what would be repaired without changing anything |
-o, --output FORMAT | Output format: pretty | json | plain |
--home DIR | Sparkwing home to inspect (default: $SPARKWING_HOME or ~/.sparkwing) |
--timeout DURATION | Budget for the daemon and local-state checks; each takes a slice of it (default: 10s) |
Examples
# Diagnose and repair now
sparkwing doctor
# Report without changing anything
sparkwing doctor --dry-run
# Agent-readable report
sparkwing doctor -o json
# Answer quickly on a machine that is already stuck
sparkwing doctor --timeout 3s