gaal sync

gaal sync [flags]

sync is the workhorse. It runs the audit, computes the plan, and applies it: clones or updates repositories, installs or refreshes skills, copies configured content, runs hooks, and upserts MCP entries.

Flags

Flag	Default	Description
`-s`, `--service`	off	Run as a continuous service (daemon mode).
`-i`, `--interval <duration>`	`5m`	Polling interval in service mode (e.g. `30s`, `10m`, `2h`).
`--dry-run`	off	Preview the plan without writing anything. See Dry-run.
`--prune`	off	Remove skills and MCP entries no longer in the config. See Pruning.
`--force`	off	Install skills into all registered agents even when not detected. Applies only to `agents: ["*"]`.

Plus all global flags.

Incompatible combinations

Combo	Result
`--dry-run --service`	Rejected, a dry-run service loop is meaningless.
`--prune --service`	Rejected, destructive operations don’t belong in a loop.

Exit codes

Code	Mode	Meaning
`0`	one-shot	Success, nothing to change or all changes applied.
`0`	`--dry-run`	No changes pending.
`1`	`--dry-run`	Changes are pending, run `gaal sync` to apply.
`2`	any	Error during planning or apply.

Examples

# One-shot sync
gaal sync

# Preview, no writes
gaal sync --dry-run

# Continuous loop, every 10 minutes
gaal sync --service --interval 10m

# Clean up orphans
gaal sync --prune

# Pre-stage a fresh machine, install for every registered agent
gaal sync --force

# Sandboxed sync (no risk to real files)
gaal --sandbox /tmp/sb sync

# Sync with structured logs
gaal --log-file /var/log/gaal.json sync --service --interval 5m

Sample output

$ gaal sync
✓ src/example          cloned
✓ code-review          installed in claude-code, cursor
✓ filesystem           upserted in ~/.claude.json
sync complete in 1.2s

If any entry in tools: is missing from PATH, sync prints a single compact banner to stderr before it starts work, then proceeds:

⚠ Required tools missing from PATH:
    rtk          — cargo install rtk
    tree-sitter  — (required by skill obra/superpowers)
  Run `gaal doctor` for details.

Each line shows the hint when one is set; otherwise it shows the source that declared the tool. Missing tools never change sync’s exit code — run gaal doctor for the full attribution and a non-zero exit code.

CLI reference

Flags

Incompatible combinations

Exit codes

Examples

Sample output

Missing tool banner

Dry-run

Pruning

Sync vs. service mode

​Flags

​Incompatible combinations

​Exit codes

​Examples

​Sample output

​Missing tool banner

​Related

Dry-run

Pruning

Sync vs. service mode

Flags

Incompatible combinations

Exit codes

Examples

Sample output

Missing tool banner

Related