# agility pull

> Source: https://agilitycms.com/docs/developers/cli-pull

`agility pull` downloads an Agility instance to local files: models, containers, content, page templates, pages, assets, galleries, sitemaps and URL redirections. Use it for a local snapshot, a backup, or to check an instance's models in CI. It only reads from the instance.

Checked against `@agility/cli` 1.1.0. For the options every command shares, sign-in and exit codes, see the [CLI command reference](/docs/developers/cli-reference).

## Usage

```bash
agility pull --sourceGuid=<guid> [options]
```

From `agility pull --help`:

```text
agility pull

Pull your Agility instance locally.
```

## Required settings

| Setting | How to provide it |
| --- | --- |
| Instance | `--sourceGuid`, or `AGILITY_GUID` in a `.env` file |
| Locales | `--locales`, `AGILITY_LOCALES` in a `.env` file, or leave both out to use every locale on the instance |
| Channel | `--channel`; defaults to `website` |
| Sign-in | A browser sign-in, or a Personal Access Token with `--token` or `AGILITY_TOKEN` |

## Options

| Option | Default | What it does in a pull |
| --- | --- | --- |
| `--sourceGuid` | from `.env` | The instance to download. One GUID per run |
| `--locales` | auto-detected | Comma-separated locale codes to download |
| `--channel` | `website` | The channel whose sitemap is downloaded |
| `--elements` | all | Comma-separated subset of `Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps,UrlRedirections`. `--elements=Models` downloads only model definitions |
| `--models` | none | Comma-separated model reference names. With `--models` and no `--models-with-deps`, only model definitions are downloaded |
| `--models-with-deps` | none | Comma-separated model reference names, plus everything they depend on |
| `--fullPull` | `false` | Ignores the stored content sync tokens, downloads all content items and pages again, and removes local content and page files that no longer exist on the instance |
| `--token` | none | Personal Access Token. Falls back to `AGILITY_TOKEN` |
| `--headless` | `false` | Logs to a file only, with no console output |
| `--verbose` | `true` | Writes all logs to the console |

`pull --help` also lists `--targetGuid`, `--pages`, `--containers`, `--preflight`, `--jsonSummary`, `--overwrite` and `--autoPublish`. They apply to sync and push, not to a pull.

## Incremental downloads

Content items and pages are downloaded with the Content Sync SDK, using the instance's **preview** API key, so the download holds the latest saved version of each item, published or not. The first pull downloads everything; later pulls into the same folder download only what changed, using a sync token stored per locale:

```text
agility-files/{guid}/{locale}/state/sync.json
```

Models, containers, templates, galleries and assets are compared with the instance on every pull, whatever the sync token says. Use `--fullPull` when the local copy may be stale, for example after copying an `agility-files` folder from another machine. (A full re-pull logs its progress with the older wording `--reset=true`.)

## Where the files go

```text
agility-files/{guid}/
├── models/            # one JSON file per model, named by model ID
├── containers/
├── templates/
├── galleries/
├── assets/
└── {locale}/          # content items, pages, sitemaps, URL redirections, sync state
```

The folder is created in the current working directory. In 1.1.0 there is no option to change it.

## Examples

```bash
# Everything, every locale
agility pull --sourceGuid="abc123-u"

# One locale
agility pull --sourceGuid="abc123-u" --locales="en-us"

# Models only (fast; useful for checking model changes in CI)
agility pull --sourceGuid="abc123-u" --elements="Models"

# Start over: ignore stored sync tokens and re-download content and pages
agility pull --sourceGuid="abc123-u" --fullPull

# In CI: token from a secret, file-only logging, pinned version
AGILITY_TOKEN="$AGILITY_TOKEN" npx @agility/cli@1.1.0 pull \
  --sourceGuid="$AGILITY_GUID" --elements="Models" --headless
```

## Exit behavior

- Exits `0` when every part of the download succeeded, and `1` when any part failed.
- In 1.1.0, if sign-in fails or a required setting is missing, `pull` stops without setting a failing exit code. In a pipeline, check that the files you need exist before using them, for example `test -n "$(ls agility-files/$AGILITY_GUID/models/*.json)"`.

## Related

- [sync and push](/docs/developers/cli-sync): copy one instance into another
- [Agility CLI](/docs/developers/cli): concepts, mappings and troubleshooting
- [Test Your Agility Integration in CI](/docs/developers/test-agility-integration-in-ci): use a models-only pull to catch model drift