Visit Agility Academy to take courses and earn certifications. It's free, and you can learn at your own pace. 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.

Current Version

The current version of this beta is 1.0.0-beta.9.0 updated August 1st 2025

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.
Dynamic Pages
- At present, we have not addressed syncing dynamic pages across instances.
- This limitation will be addressed in a future release that will allow for dynamic pages to be sync'd across instances.
First Sync
- The proper functionality of this CLI sync is contingent on a full sync being completed first, after which you may selectively sync models, content, assets, etc.
Breaking Changes since beta 8.1
- We have changed how we map files between instances, you MUST remove the generated ‘./agility-files’ folder and sync to a new instance to use the sync functionality.
- Please read more about Reference Mappings below.

Install Beta 9.0

npm install -g @agility/cli@1.0.0-beta.9.0

CLI Commands

Pull Command

Download content from an Agility CMS instance to local files.

agility pull [options]

Pull Options

Option	Type	Default	Description
--guid	string	required	Instance GUID to pull from
--locale	string	en-us	Locale to pull
--channel	string	website	Channel to pull from
--preview	boolean	true	Pull from preview (true) or live (false)
--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
--legacyFolders	boolean	false	Use legacy flat folder structure
--overwrite	boolean	false	Force overwrite existing local files
--verbose	boolean	false	Detailed console output
--headless	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 --guid="abc123" --locale="en-us" --elements="Models,Content"

# Pull with overwrite (refresh local files)
agility pull --guid="abc123" --locale="en-us" --overwrite

# Pull from live environment
agility pull --guid="abc123" --locale="en-us" --preview=false

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
--locale	string	en-us	Locale to sync
--channel	string	website	Channel to sync
--preview	boolean	true	Sync to preview (true) or live (false)
--elements	string	all	Comma-separated list: Models,Content,Assets,Pages,Galleries,Containers,Templates
--rootPath	string	agility-files	Local directory for sync files
--legacyFolders	boolean	false	Use legacy flat folder structure
--forceUpdate	boolean	false	Update existing items instead of skipping
--debug	boolean	false	Show dependency analysis without syncing
--verbose	boolean	true	Detailed console output
--headless	boolean	false	No UI, log to file only

Sync Examples

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

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

# Debug mode - show dependency analysis without syncing
agility sync --sourceGuid="abc123" --targetGuid="def456" --debug

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

# Sync to live environment
agility sync --sourceGuid="abc123" --targetGuid="def456" --preview=false

Authentication

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}/
│       ├── preview/          # Preview environment
│       │   ├── assets/       # Asset files and metadata
│       │   │   ├── json/     # Asset metadata
│       │   │   └── galleries/ # Gallery definitions
│       │   ├── item/         # Content items
│       │   ├── list/         # Content lists  
│       │   ├── page/         # Page definitions
│       │   ├── models/       # Content models
│       │   ├── containers/   # Content containers
│       │   ├── templates/    # Page templates
│       │   ├── sitemap/      # Flat sitemap
│       │   ├── nestedsitemap/ # Nested sitemap structure
│       │   ├── state/        # Sync state and tokens
│       │   ├── urlredirections/ # URL redirections
│       │   └── logs/         # Operation logs
│       └── live/             # Live environment (same structure as preview)

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/
├── {source-instance-guid}/
│   ├── mappings/
│   │   └── {target-instance-guid}.json    # Mapping file for source→target sync
│   └── {locale}/...

Mapping File Structure:

{
  "sourceGUID": "abc123-source",
  "targetGUID": "def456-target", 
  "records": [
    {
      "type": "model",
      "source": { "id": 42, "referenceName": "BlogPost", ... },
      "target": { "id": 84, "referenceName": "BlogPost", ... },
      "sourceGUID": "abc123-source",
      "targetGUID": "def456-target"
    }
  ],
  "modelIds": [[42, 84], [43, 85]],
  "contentIds": [[1001, 2001], [1002, 2002]],
  "templateIds": [[10, 20], [11, 21]],
  "pageIds": [[5, 15], [6, 16]],
  "assetIds": [[301, 401], [302, 402]],
  "galleryIds": [[50, 60], [51, 61]],
  "containerIds": [[7, 17], [8, 18]]
}

Why Mappings Are Essential

Performance Optimization:

Eliminates redundant API calls by caching entity relationships
Enables bulk operations and intelligent skipping of existing entities
Reduces sync time from hours to minutes for large instances

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 Mappings

High Skip Rates:

# If sync skips everything, data may be stale
agility sync --sourceGuid="abc123" --targetGuid="def456" --rebuildMappings

Corrupted Mappings:

# Force fresh mapping generation
agility sync --sourceGuid="abc123" --targetGuid="def456" --clearMappings

Manual Reset:

# Delete mapping file to start fresh
rm agility-files/{source-guid}/mappings/{target-guid}.json

Base URLs by Region

If pull operations fail, you may need to specify the --baseUrl for your region:

Region	Base URL
USA	https://mgmt.aglty.io
Canada	https://mgmt-ca.aglty.io
Europe	https://mgmt-eu.aglty.io
Australia	https://mgmt-aus.aglty.io

Troubleshooting

Common Issues

Authentication Failed

agility logout
agility login

Pull Operation Fails

# Try specifying the base URL for your region
agility pull --guid="abc123" --baseUrl="https://mgmt.aglty.io"

Sync Shows All Items Skipped

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

Debug Sync Issues

# Show dependency analysis without syncing
agility sync --sourceGuid="abc123" --targetGuid="def456" --debug --verbose

A -> B -> C Sync

When syncing to the C instance, we request that you wait for about 5 minutes to allow the B instance to fully propagate changes from the A instance. If synced too early you may see missing content. There is an issue tracker for this and will be fixed in an upcoming release.

Log Files

All operations create detailed logs at agility-files/logs/instancelog.txt.

Soon to be deprecated: Legacy CLI backwards compatibility

When using the --legacyFolders flag, the CLI uses a flattened structure directly in the root path:

# Use legacy flat structure 
agility pull --guid="abc123" --legacyFolders 

# Use legacy structure with custom root path 
agility pull --guid="abc123" --legacyFolders --rootPath="my-content"

Legacy Structure:

{rootPath}/ # Default: agility-files/ 
├── assets/ 
│ ├── json/ 
│ └── galleries/ 
├── item/ 
├── list/ 
├── page/ 
├── models/ 
├── containers/ 
├── templates/ 
├── sitemap/ 
├── nestedsitemap/ 
├── state/ 
├── urlredirections/ 
└── logs/

Key Differences:

Flattened: No instance GUID or locale subdirectories
Direct Access: All content types stored directly in the root path
Backwards Compatibility: Maintains compatibility with older CLI versions
Custom Root: Specify

In this Article:

Was this article helpful?