Agility Academy: take courses and earn certifications. Learn at your own pace - it's free! Learn More

CLI - Public Beta

CLI Public Beta

What is the Public Beta CLI?
Over the last few months, we've been hard at work rebuild the CLI for improved performance of downloading and syncing your data between instances. Now featuring an enhanced persistent mappings system, aligning this to be a more usable tool in your CI and data pipelines.

Beta Version

Known Issues and Caveats

Multi Instance Syncing
- Once an instance is synced using the CLI, there will be pending tasks to publish content into our CDN that need to be completed before that instance is ready to be used as the source instance for subsequent sync operations.
- The impact is that if you sync instance A to instance B, you will need to wait (the length of time this takes will be dependent on the size of the content in the instance and how much data is being processed) before instance B can be synced to instance C.
- Failing to wait will cause data loss.
- At present there is no way for a user to know when these tasks are complete and so we see it as a critical feature needed to support CLI sync operations.
- This limitation will be addressed in a future release that will delay or prevent syncing instances that have pending or errored tasks to avoid any data loss.

Install the Agility CLI

The most recent Agility CLI version can be found on the NPM page here
Our recommendation is to install the CLI using a global NPM install, selecting the specific version you would like to use.

sudo npm install -g @agility/cli@{version}

CLI Commands

Pull Command

Download content from an Agility CMS instance to local files.

agility pull [options]

Pull Options

Option	Type	Default	Description
--sourceGuid	string	required	Instance GUID to pull from
--locales	string	en-us	Locale to pull
--elements	string	all	Comma-separated list: Galleries,Assets,Models,Containers,Content,Templates,Pages
--baseUrl	string	auto-detect	Override API base URL
--rootPath	string	agility-files	Local directory for downloaded files
--update=true	boolean	false	Force overwrite existing local files
--verbose=true	boolean	true	Detailed console output
--headless=true	boolean	false	No UI, log to file only

Pull Examples

# Basic pull
agility pull --guid="abc123" --locale="en-us" --channel="website"

# Pull specific elements only
agility pull --sourceGuid ="abc123" --locales="en-us" --elements="Models,Content"

# Pull with overwrite (refresh local files)
agility pull --sourceGuid ="abc123" --locales="en-us" --update=true

# Pull from live environment
agility pull --sourceGuid ="abc123" --locales="en-us"

Sync Command

Synchronize content between two Agility CMS instances with intelligent dependency resolution.

agility sync [options]

Sync Options

Option	Type	Default	Description
--sourceGuid	string	required	Source instance GUID
--targetGuid	string	required	Target instance GUID
--locales	string	all locales	Locale to sync
--elements	string	all	Comma-separated list: Models,Content,Assets,Pages,Galleries,Containers,Templates
--rootPath	string	agility-files	Local directory for sync files
--update=true	boolean	false	Force overwrite existing local files of the sourceGuid before syncing
--overwrite=true	boolean	false	Update existing items in targetGuid instead of skipping them
--verbose=true	boolean	true	Detailed console output
--headless=true	boolean	false	No UI, log to file only
--models	comma separated list of model reference names	no default	only sync content models specified in the command
--models-with-deps	comma separated list of model reference names	no default	Sync content models and their associated content and assets

Sync Examples

# Basic sync
agility sync --sourceGuid="abc123" --targetGuid="def456"

# Sync specific elements only
agility sync --sourceGuid="abc123" --targetGuid="def456" --elements="Models,Content"

# Force update existing items
agility sync --sourceGuid="abc123" --targetGuid="def456" --overwrite

# Sync only models
agility sync --sourceGuid="abc123" --targetGuid="def456" --models="Model1,Model2,Model3"

# Sync models and dependencies
agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="Model1,Model2,Model3"

Authentication

Authentication will happen automatically when invoking a pull, push or sync command.

Login

Authenticate with Agility CMS to access your instances.

agility login

This opens a browser window for secure authentication. You must be an Org Admin, Instance Admin, or have Manager role to perform CLI operations.

Logout

agility logout

Environment Configuration

The CLI optionally supports .env file configuration for default values:

AGILITY_GUID=your-default-instance-guid
AGILITY_LOCALES=en-us,fr-ca
AGILITY_WEBSITE=website

File Structure

The CLI organizes downloaded content in a structured format:

agility-files/
├── mappings/             # Reference mappings for sync operations
├── {instance-guid}/
│   └── {locale}/
│       ├── item/         # Content items
│       ├── page/         # Page definitions
│   ├── assets/           # Asset files and metadata
│   │   ├── json/         # Asset metadata
│   ├── galleries/    # Gallery definitions
│   ├── models/           # Content models
│   ├── containers/       # Content containers
│   ├── templates/        # Page templates
│   ├── sitemap/          # Flat sitemap
│   ├── urlredirections/  # URL redirections
│   ├── state/            # Sync state and tokens
│   ├── nestedsitemap/    # Nested sitemap structure
├── logs/                 # Operation logs

Reference Mappings

Reference mappings are the core intelligence system that enables successful content synchronization between Agility CMS instances. They establish relationships between source entities and their corresponding target entities, allowing the CLI to resolve dependencies and avoid conflicts during sync operations.

How Mappings Work

When you run a sync operation, the CLI performs a mapping process:

Discovery Phase: Analyzes both source and target instances to catalog all existing entities
Mapping Creation: Establishes relationships between source and target entities using reliable identification strategies
Dependency Resolution: Uses mappings to transform entity references (like model IDs, asset URLs, content references) from source values to target values during sync

Mapping Persistence

Mappings are automatically saved to disk to optimize performance and enable incremental syncs:

agility-files/
├── mappings/
│  └──{sourceGuid}-{targetGuid}/
│    └── {locale}/
│       ├── item/         # Content items
│       ├── page/         # Page definitions
│    ├── assets/           # Asset files and metadata
│    ├── galleries/    # Gallery definitions
│    ├── models/           # Content models
│    ├── containers/       # Content containers
│    ├── templates/        # Page templates

Why Mappings Are Essential

Dependency Resolution:

Transforms content field references (model IDs, asset URLs) from source to target values
Ensures pages reference correct templates in the target instance
Maintains content relationships across instance boundaries

Conflict Prevention:

Prevents duplicate entity creation by tracking what already exists
Enables safe re-running of sync operations without data corruption
Supports incremental syncs that only process new/changed content

Multi-Instance Support:

Each source→target pair has its own mapping file
Supports complex scenarios like staging→production→backup chains
Maintains separate mapping states for different sync directions

Mapping Lifecycle

Automatic Loading:

Mappings are automatically loaded when sync operations start
Existing mappings are preserved and extended with new discoveries
Old format mappings are automatically migrated to new format

Incremental Updates:

New entities are added to mappings as they're discovered
Existing mappings are updated when target entities change
Mappings are saved after each major operation (models, content, pages, etc.)

Manual Management:

Mapping files can be manually deleted to reset sync relationships

Troubleshooting

Common Issues

Authentication Failed

agility logout
agility login

FAQs

Is it possible to pull and push only a selected set of content lists, rather than the entire instance?

No. On the first sync, all content is copied. On subsequent syncs, only newer versions of content are pulled forward via the established mappings from the initial sync. Once the mappings are established, the content is updated by versionID, new versions will be updated and duplicate versions will be skipped.

Is it possible to sync a specific subset of models and in turn sync only the content using those models?

Yes. Using the argument --models-with-deps you can target sync a single or multiple models and bring forward only the staged or published content under those models. See "Sync Options" above for more details.

How does the CLI handle linked content during the sync process? Is it copied over with the same mappings?

Yes. Linked content is copied over and mappings between related content items are preserved during the sync.

After content is copied, what state does it land in? 

Everything that is synced into the target instance lands in staging regardless of the state in the source instance and needs to be republished manually. Unpublished or deleted items are not pulled across.

Which version of the content is pulled, staging or published?

The most recent versionID is pulled along with the history of that content but will be in the staging state regardless of it’s published state in the source instance.

If content in the source environment was published and later modified but left in a staging state, which version should be expected in the target instance after a completed sync?

The most recent version will always be synced, regardless of staging or published state. Version history is also included as part of the sync.

When syncing from one environment to another, does the CLI reconcile and replace existing content, or does it only append new entries?

No. Existing content (pre initial CLI sync) in the target instance cannot be remapped or replaced.

The initial sync establishes a new mapping between source and target content. Any pre existing content in the target instance will remain and cannot be reconciled. For this reason, syncing into a blank instance is strongly recommended when the goal is environment parity.

Will the synced content have the same Content ID as the source?

No. All synced content is created with new Content IDs in the target instance.

In this Article:

Was this article helpful?