Agility CLI

A powerful command-line tool for Agility CMS that provides dependency-aware content synchronization and intelligent instance management.

Quick Start

# Install globally
npm install -g @agility/cli

Note: Authentication happens automatically when you run pull or sync commands. The login and logout commands are primarily used for troubleshooting authentication issues (see Troubleshooting).

Required Permissions: You must be an Org Admin, Instance Admin, or have Manager role to perform CLI operations.

Commands

Pull Command

Download content from an Agility CMS instance to your local file system for backup, migration, or synchronization purposes.

agility pull [options]

Pull Options

Core Instance Options:

Option	Type	Default	Description
`--sourceGuid`	string	(empty)	Source instance GUID. Optional — falls back to `AGILITY_GUID` from your `.env` file when omitted.
`--locales`	string	(empty)	Comma-separated list of locales to operate on. If not specified, locales are automatically pulled from the instance
`--channel`	string	`website`	Channel (digital channel) to pull sitemaps for. Falls back to `AGILITY_WEBSITE` from your `.env` file.

Content Selection Options:

Option	Type	Default	Description
`--elements`	string	`Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps,UrlRedirections`	Comma-separated list of elements to process
`--models`	string	(empty)	Comma-separated list of model reference names to sync (only syncs the specified models)

Authentication & Environment Options:

Option	Type	Default	Description
`--token`	string	(empty)	Personal Access Token for headless/CI authentication. Falls back to `AGILITY_TOKEN`. See PAT Authentication.
`--dev`	boolean	`false`	Internal/advanced: point the CLI at Agility's development environment instead of production.

UI & Output Options:

Option	Type	Default	Description
`--headless`	boolean	`false`	Disable logging and console/terminal output, log to file only (CI/CD)
`--verbose`	boolean	`true`	Detailed console output

Pull Examples

# Basic pull
agility pull --sourceGuid="abc123"

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

# Pull specific locales
agility pull --sourceGuid="abc123" --locales="en-us,fr-ca"

Sync Command

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

agility sync [options]

Sync Options

Core Instance Options:

Option	Type	Default	Description
`--sourceGuid`	string	(empty)	Source instance GUID (required for sync)
`--targetGuid`	string	(empty)	Target instance GUID (required for sync)
`--locales`	string	(empty)	Comma-separated list of locales to operate on. If not specified, locales are automatically pulled from the source instance. Note: For sync operations, if locales are not specified, the target instance must have all the same locales set up, or the sync will error. You can selectively sync only specific locales (e.g., `--locales="en-us"`) to avoid requiring all locales to be set up in the target instance
`--channel`	string	`website`	Channel (digital channel) whose sitemap is synced. Falls back to `AGILITY_WEBSITE` from your `.env` file.

Content Selection Options:

Option	Type	Default	Description
`--elements`	string	`Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps,UrlRedirections`	Comma-separated list of elements to process
`--models`	string	(empty)	Comma-separated list of model reference names to sync (only syncs the specified models)
`--models-with-deps`	string	(empty)	Comma-separated list of model reference names to sync with their full dependency tree — includes dependent content, pages, templates, assets, galleries, and containers
`--pages`	string	(empty)	Comma-separated list of page paths, page names, or page IDs to sync. Each selected page brings its child pages and the templates, content, models, containers, assets and galleries they need — nothing else is synced. See Selective Page Sync.
`--containers`	string	(empty)	Comma-separated list of container reference names, titles, or container IDs to sync. Syncs just those containers and what their content depends on — other containers on the same model are left alone. See Selective Container Sync.
`--contentIDs`	string	(empty)	Comma-separated list of target content IDs to process directly, bypassing the mappings lookup (e.g. `--contentIDs=121,1221`)
`--pageIDs`	string	(empty)	Comma-separated list of target page IDs to process directly, bypassing the mappings lookup (e.g. `--pageIDs=12,45`)

Operation Control Options:

Option	Type	Default	Description
`--overwrite`	boolean	`false`	Conflict-scoped override. By default, when a target item has its own changes that conflict with the source, the CLI skips it to avoid data loss. With `--overwrite`, those conflicting target items are overwritten with the source version. Non-conflicting updates are applied either way. Also covers a mapped target item that no longer exists (deleted or unpublished on the target): by default that is reported as a conflict and skipped, with `--overwrite` the item is recreated and the mapping repointed.
`--autoPublish`	string	(disabled)	Automatically publish synced items that were published in the source instance. Values: `content`, `pages`, `both`. If flag is provided without a value, defaults to `both`. Items that are only in staging (not published) in the source are skipped.
`--fullPull`	boolean	`false`	Full content re-pull. Discards the stored content sync token for every locale, re-pulls all content items and pages, and removes local content/page files that no longer exist on the instance. Use when a local cache is suspected stale. Models, containers, templates, galleries and assets reconcile against the instance on every pull regardless.
`--preflight`	boolean	`false`	Dry-run preview. Runs the full source-pull, target-pull, dependency analysis and change detection, then reports the creates/updates/skips/conflicts a real sync would produce — without writing anything to the target instance or mapping files. Exits non-zero when conflicts are detected, so CI can gate a real sync on a clean preflight.

Authentication & Environment Options:

Option	Type	Default	Description
`--token`	string	(empty)	Personal Access Token for headless/CI authentication. Falls back to `AGILITY_TOKEN`. See PAT Authentication.
`--dev`	boolean	`false`	Internal/advanced: point the CLI at Agility's development environment instead of production.

UI & Output Options:

Option	Type	Default	Description
`--headless`	boolean	`false`	Disable logging and console/terminal output, log to file only (CI/CD)
`--verbose`	boolean	`true`	Detailed console output

Sync Examples

# Basic sync (pulls fresh data by default, syncs all locales from source)
agility sync --sourceGuid="abc123" --targetGuid="def456"

# Sync specific locale only (target instance only needs this locale set up)
agility sync --sourceGuid="abc123" --targetGuid="def456" --locales="en-us"

# Sync specific elements only
agility sync --sourceGuid="abc123" --targetGuid="def456" --elements="Assets"

# Overwrite target items that conflict with the source (forces conflicting updates through)
agility sync --sourceGuid="abc123" --targetGuid="def456" --overwrite

# Preview what a sync would do without writing anything (exits non-zero if conflicts are found)
agility sync --sourceGuid="abc123" --targetGuid="def456" --preflight

# Sync only specified models (models only, no dependencies)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,BlogCategory"

# Sync models with their full dependency tree (content, pages, templates, assets, galleries, containers)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="BlogPost,BlogCategory"

# Sync one page structure and its child pages, and nothing else
agility sync --sourceGuid="abc123" --targetGuid="def456" --pages="/my-lottery"

# Sync one container, leaving the other containers on the same model alone
agility sync --sourceGuid="abc123" --targetGuid="def456" --containers="AONHomeLinks"

# Sync and auto-publish everything that was published in source
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish

# Sync and auto-publish only content (not pages)
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish=content

# Sync and auto-publish only pages
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish=pages

Advanced Topics

Auto-Publish

The --autoPublish flag lets you automatically publish synced content and/or pages in the target instance immediately after a sync completes. Only items that are published in the source instance will be published in the target — staging-only items are skipped.

Modes

Value	Behavior
`both`	Publish both content items and pages (default when flag is provided without a value)
`content`	Publish only content items
`pages`	Publish only pages

How It Works

During sync, the CLI tracks which content items and pages were successfully pushed to the target instance
It also checks the publish state of each item in the source — only items with a published state are eligible
After all sync operations complete, the CLI publishes the eligible items in the target using the batch workflow API
Publishing is done per-locale to match the workflow API requirements
After publishing, reference mappings are updated to reflect the new published versions

Examples

# Auto-publish everything (content + pages) — flag without value defaults to 'both'
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish

# Explicitly publish both
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish=both

# Publish only content items (skip pages)
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish=content

# Publish only pages (skip content)
agility sync --sourceGuid="abc123" --targetGuid="def456" --autoPublish=pages

Note: Auto-publish only works with sync operations (not pull). Items that fail to sync will not be published. Any publish errors are reported in the final summary alongside sync errors.

Model-Specific Sync

The CLI provides two options for selective synchronization based on specific content models: --models and --models-with-deps. This is particularly useful for large instances where you only want to sync certain content types.

--models

The --models parameter syncs only the specified models in CSV format. It does not include any dependencies.

# Sync only the specified models (no dependencies)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,BlogCategory"

--models-with-deps

The --models-with-deps parameter syncs the specified models plus their full dependency tree. It includes:

Content items based on those models
Pages that use those content items or their templates
Templates used by those pages
Assets referenced by the content and pages
Galleries referenced by the content and pages
Containers

# Sync models with their full dependency tree (content, pages, templates, assets, galleries, containers)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="BlogPost,BlogCategory"

Model-Specific Examples

# Sync only models (no dependencies)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,BlogCategory"

# Sync models with their full dependency tree (content, pages, templates, assets, galleries, containers)
agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="Product,ProductCategory,ProductReview"

Benefits of Model-Specific Sync

Faster Operations: Only processes relevant content instead of entire instance
Targeted Updates: Perfect for content-specific deployments
Flexible Control: Choose between models-only or models with dependencies

Selective Page Sync

--pages narrows a sync to one or more page structures. Use it when you want to promote the pages belonging to a single feature up through your environments, instead of running a full sync and resolving conflicts on every unrelated page that has drifted.

# Sync the /my-lottery page and every page underneath it
agility sync --sourceGuid="abc123" --targetGuid="def456" --pages="/my-lottery"

# Several page structures at once
agility sync --sourceGuid="abc123" --targetGuid="def456" --pages="/my-lottery,/promotions"

Naming a page

Each selector is matched, case-insensitively, against:

the page path — /my-lottery (a leading slash is optional, a trailing slash is ignored),
the page name — my-lottery, or
the page ID — 1042.

Selectors are matched across every channel in the source instance.

Git Bash on Windows: the shell rewrites a leading-slash argument into a Windows path, so --pages=/my-lottery arrives as C:/Program Files/Git/my-lottery. Drop the leading slash (--pages="my-lottery"), double it (--pages="//my-lottery"), or set MSYS_NO_PATHCONV=1. PowerShell and cmd are unaffected. The CLI detects this and says so rather than syncing the wrong thing.

What gets synced

The pages you named, plus all of their child pages, to any depth.
Everything those pages need to render on the target: the page templates they use, the content their Components reference (followed through linked-content fields, including whole lists), the models and containers behind that content, and the assets and galleries it points at.

Nothing else is touched. URL redirections, unrelated models and every page outside the selected structures are left alone on the target.

What does NOT get synced: parent pages

A selected page's parents are not synced. They are only used to work out where the selected pages belong in the target sitemap, which means they must already exist there.

If a parent has never been synced to the target, the run stops before writing anything:

❌ Parent pages of the selected pages have never been synced to the target:
  • [en-us] /products (pageID 3)
💡 Add them to --pages to sync them too, or run a sync that covers them first.

Either add the parent to --pages, or run a sync that covers it first.

Seeing the scope before anything is written

Every --pages run prints the resolved page tree before the first write, so you can confirm the scope is what you expected:

🎯 PAGE SCOPE — only these pages and their dependencies will be synced

en-us
  website
    · /products (parent — left unchanged)
      → /products/my-lottery (pageID 10)
        + /products/my-lottery/rules (pageID 11)
        + /products/my-lottery/winners (pageID 12)

→ is a page you named, + a child page that comes with it, and · a parent shown only for context. Combine with --preflight to see the creates, updates and conflicts that scope would produce without writing anything.

agility sync --sourceGuid="abc123" --targetGuid="def456" --pages="/my-lottery" --preflight

Notes and limits

--pages cannot be combined with --models, --models-with-deps or --containers; each defines a different sync scope. Run them as separate syncs.
A selector that matches no page anywhere stops the run and lists the available page paths.
With multiple locales, the scope is resolved per locale. A page that exists in one locale but not another is reported per locale rather than failing the run.

Selective Container Sync

--containers narrows a sync to one or more content containers.

Use it when several containers share a content model. Reusing one model across containers is the right thing to do — but it means --models-with-deps acts on the model and sweeps in every container built on it. If "AON Home Links" and "Mega Millions Home Links" are both built on a Home Links model, syncing the model promotes both. --containers promotes the one you name.

# Sync just this container and what its content depends on
agility sync --sourceGuid="abc123" --targetGuid="def456" --containers="AONHomeLinks"

# Several containers at once
agility sync --sourceGuid="abc123" --targetGuid="def456" --containers="AONHomeLinks,AONPromotions"

Naming a container

Each selector is matched, case-insensitively, against:

the container reference name — AONHomeLinks,
the container title as it reads in the CMS — AON Home Links, or
the container ID — 312.

What gets synced

The containers you named, and the content items in them.
Everything that content needs: the content it links to through linked-content fields (followed transitively, including whole lists), the containers that linked content lives in, the models behind all of it, and the assets and galleries it points at.

Nothing else is touched. Other containers on the same model, every page, every page template and every URL redirection are left alone on the target.

A linked container comes in with only the items that were actually linked to, not its whole contents — one reference into a large shared container does not drag the rest of it across.

Seeing the scope before anything is written

Every --containers run prints the resolved scope before the first write:

📦 CONTAINER SCOPE — only these containers and their dependencies will be synced

  → AON Home Links (AONHomeLinks) · model: HomeLinks

  Also synced, because in-scope content links to items in them:
  + Games (Games) · model: Game

  Content items in scope — en-us: 12
  Models in scope (2): Game, HomeLinks

  Other containers on these models — left unchanged on the target:
  · Mega Millions Home Links (MegaMillionsHomeLinks) · model: HomeLinks

  No pages, templates or URL redirections are touched by a container sync.

→ is a container you named, + one that came along because your content links into it, and · a container on the same model that this run leaves alone — the containers --models-with-deps would have swept in.

Combine with --preflight to see the creates, updates and conflicts that scope would produce without writing anything:

agility sync --sourceGuid="abc123" --targetGuid="def456" --containers="AONHomeLinks" --preflight

Notes and limits

--containers cannot be combined with --models, --models-with-deps or --pages; each defines a different sync scope. Run them as separate syncs.
A selector that matches no container stops the run and lists the available container names.
The model behind a selected container is synced — it has to be, or the container cannot be created on the target. What stays behind is the other containers built on that model.
With multiple locales, the container selection is the same for all of them; the content in scope is resolved per locale.

Sync Token Management

The Agility CLI uses the Content Sync SDK for incremental content synchronization. Understanding how sync tokens work is crucial for managing pull and sync operations effectively.

How Sync Tokens Work

Sync tokens are stored in the state/sync.json file and enable incremental content synchronization:

agility-files/{instance-guid}/{locale}/preview/state/sync.json
agility-files/{instance-guid}/{locale}/live/state/sync.json

Token Behavior:

First Pull: No sync token exists → Full sync downloads all content
Subsequent Pulls: Sync token exists → Incremental sync downloads only changes since last pull
Content Sync SDK: Automatically manages token creation and updates
Management SDK: Templates, models, containers, assets, galleries don't use sync tokens

Reference Mappings

Reference mappings persist state between two Agility CMS instances during sync operations. 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 persist state between sync operations:

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

⚠️ CRITICAL WARNING: Mapping File Safety

If you lose your mappings, syncing again will result in duplicate content being created in the target instance. The CLI uses mappings to identify existing content and avoid duplicates. Without mappings, it cannot determine what already exists and will create new items.

Recommended Practices:

Persist your mappings through shared file storage or a repository (e.g., Git) when working on a team

Do not run multiple CLI processes against the same source→target pair at the same time - each invocation handles exactly one source/target pair; running two overlapping processes against that same pair can still cause mapping conflicts and duplicate content

Back up your agility-files/mappings/ directory before performing destructive operations

Reverse Sync

Push changes made in the target instance back to the source instance, reusing the mapping files from the original sync.

agility reverse-sync --sourceGuid <original-source> --targetGuid <original-target> [options]

Pass the same --sourceGuid / --targetGuid you used for the forward sync. The CLI swaps the direction internally: it reads from the original target and writes into the original source. All other sync options (--locales, --models, --preflight, --autoPublish, ...) work the same way.

How it reuses mappings

Mapping files stay in agility-files/mappings/{sourceGuid}-{targetGuid}/ in their original orientation. No {targetGuid}-{sourceGuid} directory is created.
Items that were synced forward are matched through the existing mapping records, so they are updated in the source rather than duplicated.
Items that exist only in the target (created there after the forward sync) are created in the source, and a new mapping record is appended to the original file. A later forward sync picks that record up and treats the pair as already synced.
Because reverse-sync writes to the original source instance, the CLI snapshots the mapping pair to agility-files/mappings-backups/{sourceGuid}-{targetGuid}/{timestamp}/ before the first write of each run (skipped in --preflight).

Semantics to be aware of

Sync never deletes. Items that exist only in the source are left alone.
Do not run a forward sync and a reverse-sync against the same pair at the same time. Both rewrite the same mapping files and will clobber each other.
Run reverse-sync --preflight first, review the report, then run for real.

# Forward sync A → B
agility sync --sourceGuid A --targetGuid B --locales en-us

# Later: pull B's edits back into A, reusing mappings/A-B
agility reverse-sync --sourceGuid A --targetGuid B --locales en-us --preflight
agility reverse-sync --sourceGuid A --targetGuid B --locales en-us

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

Configuration

Environment Variables

For CI/CD pipelines and automation, you can configure the CLI using environment variables. Command line arguments always override environment variables when both are provided.

Environment Variable	Command Argument	Description
`AGILITY_GUID`	`--sourceGuid`	Default source instance GUID
`AGILITY_TARGET_GUID`	`--targetGuid`	Default target instance GUID
`AGILITY_LOCALES`	`--locales`	Comma-separated list of locales to operate on
`AGILITY_WEBSITE`	`--channel`	Default channel name
`AGILITY_ELEMENTS`	`--elements`	Default elements to process
`AGILITY_MODELS`	`--models`	Default models to sync (comma-separated, models only)
`AGILITY_VERBOSE`	`--verbose`	Default verbose output setting
`AGILITY_HEADLESS`	`--headless`	Default headless mode setting
`AGILITY_OVERWRITE`	`--overwrite`	Default overwrite setting (sync only)
`AGILITY_DEV`	`--dev`	Internal/advanced: target Agility's development environment
`AGILITY_TOKEN`	`--token`	Personal Access Token for headless/CI authentication (see below)

Personal Access Token (PAT) Authentication

The CLI supports two authentication methods:

Browser-based (default): OAuth login opens automatically when you run pull or sync. Best for interactive use.
Personal Access Token: A long-lived token you provide directly. Best for CI/CD pipelines, automation, and headless environments where a browser cannot open.

Getting a Personal Access Token

There is no UI for token management yet. PATs must be created by calling the Management API directly with an OAuth bearer token.

Step 1 — Log in via the CLI to get an OAuth token

agility login

This opens a browser window to authenticate and stores your OAuth token in the system keychain.

Step 2 — Extract your OAuth token from the keychain

On macOS:

security find-generic-password -s "agility-cli" -a "cli-auth-token:prod" -w | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['access_token'])"

On Linux (GNOME keyring):

secret-tool lookup service agility-cli account cli-auth-token:prod | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['access_token'])"

Step 3 — Determine your Management API base URL

The URL is determined by the last character(s) of your instance GUID:

GUID suffix	Base URL
`u`	`https://mgmt.aglty.io`
`c`	`https://mgmt-ca.aglty.io`
`e`	`https://mgmt-eu.aglty.io`
`a`	`https://mgmt-aus.aglty.io`
`us2`	`https://mgmt-usa2.aglty.io`

Step 4 — Create the PAT

curl -X POST "https://mgmt.aglty.io/api/v1/tokens/create" \
  -H "Authorization: Bearer <your-oauth-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "my-ci-token",
    "ExpiryDate": "2027-12-31T00:00:00Z"
  }'

Name is required (1–100 characters, unique per user)
ExpiryDate is optional — defaults to 2 years from now if omitted (maximum allowed)

Step 5 — Copy the token from the response

A successful 201 response looks like:

{
  "tokenID": "550e8400-...",
  "name": "my-ci-token",
  "expiryDate": "2027-12-31T00:00:00Z",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Copy the token value immediately — it is only returned at creation time and cannot be retrieved again.

Constraints:

Maximum 10 active tokens per user
Maximum 2-year expiry per token
Tokens cannot be used to create or manage other tokens — OAuth login is required for token management
Rate limited to 5 creation requests per hour

Using a PAT with the CLI

Pass the token via the --token flag or the AGILITY_TOKEN environment variable:

# Pass as a flag
agility pull --sourceGuid="abc123" --token="your-pat-here"

# Or set as an environment variable
export AGILITY_TOKEN="your-pat-here"
agility pull --sourceGuid="abc123"

# Or add it to your .env file
echo 'AGILITY_TOKEN=your-pat-here' >> .env

Once provided, the CLI stores the PAT securely in your system keychain. Subsequent commands in the same environment will use the stored token automatically.

For CI/CD pipelines, combine AGILITY_TOKEN with --headless to suppress interactive output:

AGILITY_TOKEN="your-pat-here" agility sync \
  --sourceGuid="abc123" \
  --targetGuid="def456" \
  --headless

Troubleshooting

Authentication Issues

Authentication happens automatically when you use pull or sync commands. However, if you encounter authentication errors, you can manually manage your authentication:

# Clear existing authentication
agility logout

# Re-authenticate (opens browser window)
agility login

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

Log Files

All operations create detailed logs. Check the following locations:

Operation logs: agility-files/{instance-guid}/{locale}/preview/logs/ or agility-files/{instance-guid}/{locale}/live/logs/
General logs: agility-files/logs/ (if applicable)

Contributing

Branching and Development

All work happens on feature branches off main. When your change is ready, open a pull request and squash-merge it into main. This keeps the commit history on main linear and easy to read.

# Start a feature
git checkout main && git pull
git checkout -b feat/my-feature

# ... make changes ...

# Push and open a PR, then squash-merge via GitHub

Releasing to npm

Releases are published to npm automatically via GitHub Actions when a version tag is pushed to a commit on main.

Steps:

Bump the version in package.json on main (directly or via a PR)
Pull the latest main locally, then tag and push:

git checkout main && git pull
git tag v1.0.0-beta.14.0
git push origin v1.0.0-beta.14.0

The workflow will verify the tag is on main, build the project, and publish to npm. Tags pushed on non-main commits are ignored.

Required secret: The repo must have an NPM_TOKEN secret (Settings → Secrets → Actions) set to an npm Automation token with publish access to @agility/cli.

Support

Documentation: Agility CMS Help Center
Community: Agility Slack
Issues: GitHub Issues
Website: agilitycms.com

Built with ❤️ by the Agility CMS team

Name		Name	Last commit message	Last commit date
.claude/agents		.claude/agents
.github/workflows		.github/workflows
.vscode		.vscode
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.watchmanconfig		.watchmanconfig
README.md		README.md
changelog.md		changelog.md
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
license.txt		license.txt
package-lock.json		package-lock.json
package.json		package.json
structure.txt		structure.txt
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
yarn.lock		yarn.lock

Latest commit

History

Folders and files

Repository files navigation

Agility CLI

Quick Start

Required Permissions: You must be an Org Admin, Instance Admin, or have Manager role to perform CLI operations.

Commands

Pull Command

Pull Options

Pull Examples

Sync Command

Sync Options

Sync Examples

Advanced Topics

Auto-Publish

Modes

How It Works

Examples

Model-Specific Sync

--models

--models-with-deps

Model-Specific Examples

Benefits of Model-Specific Sync

Selective Page Sync

Naming a page

What gets synced

What does NOT get synced: parent pages

Seeing the scope before anything is written

Notes and limits

Selective Container Sync

Naming a container

What gets synced

Seeing the scope before anything is written

Notes and limits

Sync Token Management

How Sync Tokens Work

Reference Mappings

How Mappings Work

Mapping Persistence

Reverse Sync

How it reuses mappings

Semantics to be aware of

File Structure

Configuration

Environment Variables

Personal Access Token (PAT) Authentication

Getting a Personal Access Token

Using a PAT with the CLI

Troubleshooting

Authentication Issues

Log Files

Contributing

Branching and Development

Releasing to npm

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages