Using gaal doctor

​

What doctor checks

$ gaal doctor
config:
  ✓ ./gaal.yaml parses against schema 1
  ✓ no scope-restricted fields in workspace
sources:
  ✓ anthropics/skills          reachable
  ✓ vercel-labs/agent-skills   reachable
mcps:
  ✓ ~/.claude.json   writable
  ✓ ~/.cursor/mcp.json                            writable
tools:
  ✓ gh           (on PATH: /opt/homebrew/bin/gh)
  ! rtk          — missing from PATH (required by: workspace; hint: cargo install rtk)
agents:
  installed: claude-code, cursor, codex
  not installed: github-copilot, windsurf
telemetry:
  ✓ disabled (per ~/.config/gaal/config.yaml)

3 agents installed, 0 misconfigured

1. Config validity, does gaal.yaml parse? Does it conform to the schema? Are scope-restricted fields used in the wrong scope?
2. Source reachability, every skills[*].source and every mcps[*].source URL is contacted (HEAD only, no download).
3. MCP target writability, every mcps[*].target file is checked for read/write permission. Missing files are OK; the target will be created on sync.
4. Tool presence, every entry under top-level tools: and per-skill tools: is looked up on PATH with exec.LookPath. Missing tools warn (exit code 1) and show the hint when one is declared. See schema/tools.
5. Agent installation, for each agent in the registry, doctor reports whether gaal detects it on this machine.
6. Telemetry status, opt-in / opt-out, plus the source file the value came from.

​

Exit codes

gaal doctor && echo "ready to sync"

​

Useful flags

gaal doctor --offline      # skip network reachability checks
gaal doctor --no-upsell    # suppress the Community Edition graduation message
gaal doctor -o json        # machine-readable output

​

Reading doctor output

​

Common things doctor catches

• A workspace gaal.yaml trying to set telemetry:.
• An mcps[].target whose parent directory doesn’t exist and isn’t writable by the current user.
• A skills[].source URL that 404s or requires authentication you haven’t set up.
• An MCP target file that’s not valid JSON (someone hand-edited it incorrectly).
• A custom agents file at ~/.config/gaal/agents.yaml that overrides a built-in entry.

​

Related