> ## 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 sync

> Reconcile every resource in gaal.yaml against the filesystem.

```bash theme={"theme":"nord"}
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](/workflows/dry-run).                      |
| `--prune`                     | off     | Remove skills and MCP entries no longer in the config. See [Pruning](/workflows/pruning).          |
| `--force`                     | off     | Install skills into all registered agents even when not detected. Applies only to `agents: ["*"]`. |

Plus all [global flags](/cli/overview#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

```bash theme={"theme":"nord"}
# 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

```text theme={"theme":"nord"}
$ gaal sync
✓ src/example          cloned
✓ code-review          installed in claude-code, cursor
✓ filesystem           upserted in ~/.claude.json
sync complete in 1.2s
```

## Missing tool banner

If any entry in [`tools:`](/schema/tools) is missing from `PATH`, sync prints a single compact banner to stderr before it starts work, then proceeds:

```text theme={"theme":"nord"}
⚠ 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`](/cli/doctor) for the full attribution and a non-zero exit code.

## Related

<CardGroup cols={2}>
  <Card title="Dry-run" icon="eye" href="/workflows/dry-run" />

  <Card title="Pruning" icon="scissors" href="/workflows/pruning" />

  <Card title="Sync vs. service mode" icon="repeat" href="/workflows/sync-vs-service" />
</CardGroup>