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

# Quickstart

> From zero to a synced machine in five minutes.

By the end of this page you'll have a working `gaal.yaml`, every detected agent skill imported into it, and a clean `gaal sync` that completes without errors.

## 1. Confirm the install

```bash theme={"theme":"nord"}
$ gaal version
gaal v0.3.0
built 2026-04-18T09:00:00Z
```

If this fails, head back to [Install](/install).

## 2. See what's on your machine

`gaal audit` scans your project, your home directory, and each agent's package-manager paths for skills and MCP servers, without writing anything.

```bash theme={"theme":"nord"}
$ gaal audit
discovered:
  skills (project)
    .claude/skills/code-review     (claude-code)
    .cursor/skills/test-writer     (cursor)
  skills (global)
    ~/.claude/skills/git-helper    (claude-code)
  mcps
    ~/.claude.json
      filesystem, git
```

This is read-only, nothing is changed yet.

## 3. Initialise gaal.yaml

The interactive wizard turns the audit into a real config file:

```bash theme={"theme":"nord"}
$ gaal init
? How should we create your gaal.yaml?
  ▸ Import everything detected on this machine
    Start from an empty documented skeleton
? Where should this configuration apply?
  ▸ Project (./gaal.yaml)
    Global (~/.config/gaal/config.yaml)
```

After confirming, `init` writes a fully-populated `gaal.yaml` to the chosen path.

<Tip>
  **No TTY?** Use the non-interactive form:

  ```bash theme={"theme":"nord"}
  gaal init --import-all --scope project
  ```

  `--empty` and `--import-all` are mutually exclusive; one is required when stdin isn't a TTY.
</Tip>

## 4. Preview the sync

Always preview before the first real sync. `--dry-run` runs the full planner without touching disk.

```bash theme={"theme":"nord"}
$ gaal sync --dry-run
plan:
  repositories
    + clone   src/example          (git, main)
  skills
    + install code-review          → claude-code, cursor
    = unchanged git-helper         → claude-code
  mcps
    + upsert  filesystem           → ~/.claude.json
```

Exit codes: **0** = nothing to do, **1** = changes pending, **2** = error.

## 5. Optional: add a registry skill

You can search the default registry without changing your config:

```bash theme={"theme":"nord"}
gaal skill search frontend
```

For the default `skills.sh` registry, this uses `npx skills find` behind the scenes. Make sure `npx` is available on `PATH`. You do not need `VERCEL_OIDC_TOKEN` or skills.sh API auth.

Install adds the selected skill to `gaal.yaml` and runs sync by default:

```bash theme={"theme":"nord"}
gaal skill install frontend-design
```

Use `--project` if the skill should live only in this repo, or `--no-sync` if you want to review the YAML before syncing.

## 6. Sync for real

```bash 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
```

## 7. Check your work

```bash theme={"theme":"nord"}
$ gaal status
repositories
  src/example          git · main · clean
skills
  code-review          claude-code, cursor
  git-helper           claude-code
mcps
  filesystem           ~/.claude.json
```

```bash theme={"theme":"nord"}
$ gaal doctor
✓ config: gaal.yaml is valid
✓ skills: all sources reachable
✓ mcps:   all target files writable
✓ agents: 3 installed, 0 misconfigured
```

## You're done

Commit `gaal.yaml` to your dotfiles repo and `gaal sync` will reproduce this exact setup on every other machine you own.

<CardGroup cols={2}>
  <Card title="How gaal works" icon="diagram-project" href="/how-gaal-works">
    The mental model behind sync, audit, and renderers.
  </Card>

  <Card title="Find skills" icon="magnifying-glass" href="/cli/skill">
    Search and install registry skills.
  </Card>

  <Card title="Sharing across machines" icon="cloud-arrow-up" href="/workflows/sharing-across-machines">
    The dotfiles pattern in detail.
  </Card>

  <Card title="Add an MCP server" icon="plug" href="/configure/mcp-servers">
    Inline definitions and remote sources.
  </Card>

  <Card title="Continuous service mode" icon="repeat" href="/workflows/sync-vs-service">
    Run gaal as a daemon that re-syncs on a schedule.
  </Card>
</CardGroup>