spt doctor

The spt doctor command runs a comprehensive health check of your development environment. It validates toolchains, configuration, services, and connectivity — then reports pass, warning, or failure status for each check.

Usage

spt doctor              # Full health check
spt doctor --fix        # Show suggested fix commands
spt doctor --json       # Machine-readable JSON output
spt doctor -c node      # Check a single component
spt doctor --verbose    # Verbose mode (runs cargo check)
spt doctor --install    # Auto-install missing dependencies

All Health Checks

The doctor runs 19 checks in parallel for fast results. Each check returns one of three statuses:

Status	Meaning
pass	Healthy — no action needed
warn	Degraded — optional dependency missing or version outdated
fail	Broken — required dependency missing or critical issue

Core Toolchain

Check	What it validates	Fix hint
Version Freshness	Current spt version vs. latest release; detects stale installations	cargo install spt-cli
Node.js Version	Node.js >= 20 required (18 warns, <18 fails)	nvm install 20 && nvm use 20
npm Version	npm >= 9 recommended	npm install -g npm@latest
TypeScript	Local TypeScript compiler availability	npm install -D typescript
Git	Git is installed	Install from git-scm.com
Git Repository	Current directory is a git repo	git init

Optional Toolchains

Check	What it validates	Fix hint
Rust Toolchain	rustc and cargo are available (needed for crate builds)	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
wasm-pack	Available for WebAssembly builds	cargo install wasm-pack
Go	Go >= 1.21 (needed for Go CLI)	brew install go or go.dev/dl
NATS Server	nats-server binary or NATS_URL env var set	brew install nats-server
Cargo Workspace	Parses Cargo.toml workspace members; runs cargo check in verbose mode	cargo check --workspace

Runtime & Services

Check	What it validates	Fix hint
Config File	Looks for .sptflo/config.json, sptflo.config.json, or .sptflo.json	sptflo config init
Daemon Status	Checks .sptflo/daemon.pid and whether the process is alive	sptflo daemon start
Memory Database	Looks for SQLite database in .sptflo/, .swarm/, or data/	sptflo memory configure --backend hybrid
sptflo	Checks local node_modules for sptflo package and its feature exports	npm install sptflo@latest

Integration

Check	What it validates	Fix hint
Claude Code CLI	claude command is available	npm install -g @anthropic-ai/claude-code
API Keys	ANTHROPIC_API_KEY, CLAUDE_API_KEY, or OPENAI_API_KEY in environment	export ANTHROPIC_API_KEY=your_key
MCP Servers	MCP config exists and sptflo is registered	claude mcp add sptflo ...
Disk Space	Filesystem usage below 80% (warns) / 90% (fails)	Free up disk space

Checking a Single Component

Use -c to run one check in isolation. Valid component names:

spt doctor -c version      # Version freshness
spt doctor -c node         # Node.js version
spt doctor -c npm          # npm version
spt doctor -c claude       # Claude Code CLI
spt doctor -c git          # Git installation
spt doctor -c config       # Config file
spt doctor -c daemon       # Daemon status
spt doctor -c memory       # Memory database
spt doctor -c api          # API keys
spt doctor -c mcp          # MCP servers
spt doctor -c disk         # Disk space
spt doctor -c typescript   # TypeScript compiler
spt doctor -c sptflo       # sptflo package
spt doctor -c rust         # Rust toolchain
spt doctor -c wasm         # wasm-pack
spt doctor -c nats         # NATS server
spt doctor -c cargo        # Cargo workspace
spt doctor -c go           # Go version

Example Output

sptflo Doctor
System diagnostics and health check
──────────────────────────────────────────────────

✓ Version Freshness: v3.0.0-alpha.90 (up to date)
✓ Node.js Version: v22.4.0 (>= 20 required)
✓ npm Version: v10.8.1
✓ Claude Code CLI: v1.0.23
✓ Git: v2.43.0
✓ Git Repository: In a git repository
⚠ Config File: No config file (using defaults)
⚠ Daemon Status: Not running
⚠ Memory Database: Not initialized
⚠ API Keys: No API keys found
⚠ MCP Servers: No MCP config found
✓ Disk Space: 45G available
✓ TypeScript: v5.6.3
⚠ sptflo: Not installed (optional)
✓ Rust Toolchain: rustc 1.82.0, cargo 1.82.0
⚠ wasm-pack: Not installed (optional, needed for wasm builds)
⚠ NATS Server: Not available (optional, needed for messaging)
✓ Cargo Workspace: 28 crates (use --verbose for cargo check)
✓ Go: v1.23

──────────────────────────────────────────────────

Summary: 10 passed, 8 warnings

Run with --fix to see 8 suggested fixes

JSON Output for CI

Use --json for structured output suitable for CI pipelines:

spt doctor --json

{
  "success": true,
  "summary": {
    "passed": 10,
    "warnings": 8,
    "failed": 0,
    "total": 18
  },
  "checks": [
    {
      "name": "Node.js Version",
      "status": "pass",
      "message": "v22.4.0 (>= 20 required)"
    }
  ]
}

The command exits with code 1 if any check has fail status, making it suitable for CI gates:

# GitHub Actions example
- name: Check environment
  run: spt doctor --json

The --fix Flag

When run with --fix, the doctor displays the fix command for every warning and failure:

spt doctor --fix

⚠ Config File: No config file (using defaults)
  Config File: sptflo config init

⚠ Daemon Status: Not running
  Daemon Status: rm .sptflo/daemon.pid && sptflo daemon start

⚠ API Keys: No API keys found
  API Keys: export ANTHROPIC_API_KEY=your_key

TIP

The --install flag goes further and auto-installs missing dependencies like the Claude Code CLI. Use it for one-command setup:

spt doctor --install

Next Steps

• Your First Project — start building with SPT