Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getgaal.com/llms.txt

Use this file to discover all available pages before exploring further.

gaal doctor is the diagnostic command. Run it any time gaal isn’t behaving the way you expect, it’s faster than reading the source.

​
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
In order, doctor checks:
  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

CodeMeaning
0Everything passed.
1Warnings only, gaal will function, but something is suboptimal (e.g. an unreachable optional source).
2Errors, gaal cannot operate as configured.
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
--offline is what you want in CI environments without internet access, or when running over a metered connection.

​
Reading doctor output

The output is grouped by check category. Within each category, lines are prefixed with:
PrefixSeverity
✓Passed.
!Warning, not blocking, but worth attention.
✗Error, blocks sync.
Errors always come with a hint about how to fix them.

​
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.
For step-by-step fixes to specific errors, see Common errors.

Common errors

FAQ

gaal doctor reference