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

Usage

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

From agility pull --help:

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:

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

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

# 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: copy one instance into another
• Agility CLI: concepts, mappings and troubleshooting
• Test Your Agility Integration in CI: use a models-only pull to catch model drift