What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
APIs
Every command and option in the Agility CLI 1.1.0: shared options, browser and Personal Access Token sign-in, .env configuration, exit codes and the files the CLI writes.
This reference covers every command and option in the Agility CLI, @agility/cli version 1.1.0 (published to npm on October 2, 2026). Every option listed here appears in the CLI's own --help output for that version, except one hidden option on workflows, which is called out on its page.
| Command | Aliases | What it does | Reference |
|---|---|---|---|
agility login | Signs in through the browser, or stores a Personal Access Token | login and logout | |
agility logout | Removes the stored sign-in and any stored Personal Access Token | login and logout | |
agility pull | Downloads an instance to local files | pull | |
agility push | sync | Copies one instance into another, with dependency resolution and mappings | sync and push |
agility reverse-sync | Copies changes from the target of an earlier sync back into its source | reverse-sync | |
agility workflows | workflow | Publishes, unpublishes, approves, declines or requests approval for synced items | workflows |
Running agility with no command, or with a command it doesn't recognize, prints a short list of commands and exits with code 0. That list names a workflowOperation command; the actual command is workflows.
The package installs two command names, agility and agility-cli, which run the same program. Pin the version so a new release can't change behavior under you:
# one-off, no install
npx @agility/cli@1.1.0 --help
# project-local, pinned (recommended for CI)
npm install --save-dev @agility/cli@1.1.0
npx agility --version
Every run prints Welcome to Agility CLI. before anything else, including --version. --help and --version work on every command and exit with code 0.
The CLI ignores options it doesn't recognize. It doesn't stop or warn. A typo such as --prefight instead of --preflight runs a real sync, so copy flag names from this reference and check the run's first lines of output.
Every command's --help lists the same shared options, whether or not that command uses them. The Used by column says which commands act on each one. Most options also accept other spellings (for example --source-guid, --source or --SOURCEGUID for --sourceGuid); the main ones are listed.
| Option | Other spellings | Type | Default | Used by | What it does |
|---|---|---|---|---|---|
--sourceGuid | --source-guid, --source | string | from .env | pull, sync, push, reverse-sync, workflows | The instance to read from. One GUID only. Falls back to AGILITY_GUID in a .env file |
--targetGuid | --target-guid, --target | string | from .env | sync, push, reverse-sync, workflows | The instance to write to. One GUID only. Falls back to AGILITY_TARGET_GUID in a .env file |
--locales | --Locales, --LOCALES | string | auto-detected | all except login, logout | Comma-separated locale codes, for example en-us,fr-ca. When omitted, the instance's locales are detected |
--channel | string | website | pull, sync, push, reverse-sync | The channel (sitemap) to work with | |
--elements | string | all nine | pull, sync, push, reverse-sync | Comma-separated subset of Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps,UrlRedirections | |
--models | string | none | pull, sync, push, reverse-sync | Comma-separated model reference names. Filters to those models and their direct content | |
--modelsWithDeps | --models-with-deps | string | none | pull, sync, push, reverse-sync | Comma-separated model reference names, with their full dependency tree: content, pages, assets, galleries, templates and containers |
--pages | --page | string | none | sync, push, reverse-sync | Page paths, names or IDs. Syncs those pages, their child pages and what they need |
--containers | --container | string | none | sync, push, reverse-sync | Container reference names, titles or IDs. Syncs those containers and what their content needs |
--preflight | --pre-flight | boolean | false | sync, push, reverse-sync | Dry run: reports what would change, writes nothing, exits 1 if it finds conflicts |
--overwrite | boolean | false | sync, push, reverse-sync (the help text says sync only) | Lets the source version replace target items that changed on both sides | |
--autoPublish | --auto-publish | string | off | sync, reverse-sync | After the sync, publishes items that are published in the source: content, pages or both (the flag alone means both) |
--fullPull | --full-pull | boolean | false | pull, sync, push, reverse-sync | Discards stored content sync tokens and re-pulls all content and pages |
--jsonSummary | --json-summary | string | none | sync, push, reverse-sync | Writes a machine-readable JSON summary of the run to this path |
--token | string | none | every command that signs in | A Personal Access Token. Falls back to AGILITY_TOKEN | |
--headless | boolean | false | all | Logs to a file only, with no console output. (The help text still describes an older "Blessed UI"; in 1.1.0 this option selects file-only logging.) | |
--verbose | boolean | true | all | Writes all logs to the console. --headless overrides it | |
--dev | boolean | false | all | Internal: points the CLI at Agility's development servers instead of production. Don't use it with a production instance | |
--help | boolean | all | Shows help for the command | ||
--version | boolean | all | Shows the CLI version |
workflows adds --list, --contentIDs and --pageIDs, and reads a hidden --operationType. See workflows.
Not options in 1.1.0: --preview, --baseUrl, --update and --reset. Older guides mention some of them. Because unknown options are ignored, passing them has no effect. --rootPath is no longer a documented option, but 1.1.0 still honours it. Don't rely on it.
The CLI needs an Agility user with the Org Admin, Instance Admin or Manager role on the instances it works with. It signs in one of two ways.
| Browser sign-in (OAuth) | Personal Access Token (PAT) | |
|---|---|---|
| Best for | Working at your own machine | CI/CD and any machine without a browser |
| How | agility login, or automatically on the first command that needs it | --token=<pat> or the AGILITY_TOKEN environment variable |
| What happens | Opens your browser at Agility's sign-in page and waits up to 60 seconds for you to finish | No browser. The token is used directly |
| Where it's kept | The system keychain, under the service name agility-cli | The system keychain too, when one is available, so later runs on that machine reuse it |
| Removed by | agility logout | agility logout (the stored copy), or revoking the token |
The CLI looks for credentials in this order:
--token on the command line.AGILITY_TOKEN, from the environment or a .env file. If both set it, the .env file's value is used.A PAT must be at least 20 characters of letters, digits and -_.+=/. If the value you pass doesn't look like that, the CLI prints Invalid Personal Access Token format. Falling back to Auth0 authentication. and tries the browser sign-in. On a CI runner that has no browser, the run then fails after the 60-second wait, so check the secret's value first.
The CLI prints Using Personal Access Token for authentication. when it uses a PAT. It doesn't print the token itself.
To create a PAT, see Personal Access Tokens. A PAT acts as the user who created it, with that user's permissions on every instance they can reach, so store it as a CI secret and never commit it.
Before it reads the command line, the CLI looks in the current working directory for these files, in this order: .env, .env.local, .env.development, .env.production. In 1.1.0, four keys in them take effect:
| Key | Same as | Also read from the process environment? |
|---|---|---|
AGILITY_GUID | --sourceGuid | No |
AGILITY_TARGET_GUID | --targetGuid | No |
AGILITY_LOCALES | --locales | No |
AGILITY_TOKEN | --token | Yes |
# are ignored.AGILITY_WEBSITE, AGILITY_ELEMENTS, AGILITY_MODELS, AGILITY_OVERWRITE, AGILITY_VERBOSE, AGILITY_HEADLESS and AGILITY_DEV, but in 1.1.0 the matching options' defaults replace those values, so they have no effect. Pass --channel, --elements, --models, --overwrite, --verbose, --headless and --dev on the command line instead.Only AGILITY_TOKEN is read from the process environment. Setting AGILITY_GUID or AGILITY_TARGET_GUID as a CI environment variable does nothing on its own: pass the GUIDs as --sourceGuid and --targetGuid, or write them to a .env file in the step before the CLI runs.
What each command returns in 1.1.0, from the package source:
| Command | Exits 0 | Exits 1 |
|---|---|---|
sync, push, reverse-sync | The run finished without blocking failures | Sign-in failed or API keys for an instance couldn't be retrieved; a precondition failed (for example a requested locale is missing on the target, or reverse-sync got the same GUID twice); the run reported failures; the run crashed; --preflight found conflicts |
pull | Every instance downloaded without failures | Any download failed |
workflows | The operation finished without failed items | Any item failed |
login, logout | Normal completion | |
no command, unknown command, --help, --version | Always |
In 1.1.0, when pull, workflows or login can't sign in, or pull or workflows is missing required settings, the command stops without setting a failing exit code. In CI, check the output for the result you expect (for example, that the files you need exist) rather than relying on the exit code alone for those commands. sync, push and reverse-sync do exit 1 in these cases.
For pipelines that need more than an exit code, sync, push and reverse-sync can write a JSON summary with --jsonSummary. See sync and push.
Everything goes under an agility-files/ folder in the working directory. In 1.1.0 there is no documented option to change the location. The undocumented --rootPath still changes it, but don't rely on it.
agility-files/
├── {instance-guid}/ # one folder per instance pulled
│ ├── models/ containers/ templates/ galleries/ assets/ ...
│ └── {locale}/ # content items, pages, sitemaps, sync state, logs
├── mappings/{sourceGuid}-{targetGuid}/ # source-to-target mappings, written by sync
├── mappings-backups/ # snapshots taken by reverse-sync before it writes
└── logs/
Keep agility-files/mappings/ safe: it's how repeated syncs know which target item matches which source item. Losing it makes the next sync create duplicates. See Agility CLI.
The top-level help for 1.1.0, as printed by npx @agility/cli@1.1.0 --help:
agility
Default command - shows available commands
Commands:
agility Default command - shows available commands [default]
agility login Login to Agility.
agility logout Log out of Agility.
agility pull Pull your Agility instance locally.
agility push Push your instance using the new 2-pass dependency
system. [aliases: sync]
agility reverse-sync Sync the target instance back to the source instance,
reusing (and updating) the mapping files from the
original sync. Pass the same --sourceGuid/--targetGuid
as the forward sync.
agility workflows Perform workflow operations (publish, unpublish,
approve, decline, requestApproval) on content and pages
from existing mappings. [aliases: workflow]
Options:
--help Show help [boolean]
--version Show version number [boolean]
agility pull --helpagility pull
Pull your Agility instance locally.
Options:
--help Show help [boolean]
--version Show version number [boolean]
--token Provide your personal access token.
Or use AGILITY_TOKEN from .env file
if available. [string]
--dev Enable developer mode
[boolean] [default: false]
--headless Turn off the experimental Blessed UI
for operations.
[boolean] [default: false]
--verbose Run in verbose mode: all logs to
console, no UI elements. Overridden
by headless.
[boolean] [default: true]
--locales, --Locales, --LOCALES Provide locale(s) for the operation.
Comma-separated for multiple locales
(e.g., 'en-us,en-ca,fr-fr'). If not
provided, all available locales will
be auto-detected and used. [string]
--channel Provide the channel for the
operation. If not provided, will use
AGILITY_WEBSITE from .env file if
available.
[string] [default: "website"]
--elements Comma-separated list of elements to
process (Models,Galleries,Assets,Con
tainers,Content,Templates,Pages,Site
maps,UrlRedirections)
[string] [default: "Models,Galleries,Assets,Containers,Content,Templates,Pages
,Sitemaps,UrlRedirections"]
--models Comma-separated list of model
reference names to sync. Filters
only specified models and their
direct content.
[string] [default: ""]
--modelsWithDeps, --models-with-deps, Comma-separated list of model
--modelswithDeps, --ModelsWithDeps, reference names to sync with full
--MODELSWITHSDEPS dependency tree. Automatically
includes all dependent content,
pages, assets, galleries, templates,
and containers.
[string] [default: ""]
--pages, --Pages, --PAGES, --page, (sync/push only) Sync only these
--Page pages and everything beneath them.
Accepts a comma-separated list of
page paths (e.g. '/my-lottery'),
page names, or page IDs. Each
selected page brings its child pages
and the templates, content, models,
containers, assets and galleries
those pages need — nothing else is
synced. The resolved page tree is
printed before anything is written.
Parent pages of a selection are NOT
synced, and must already exist in
the target. Cannot be combined with
--models or --models-with-deps.
[string] [default: ""]
--containers, --Containers, (sync/push only) Sync only these
--CONTAINERS, --container, --Container content containers and what they
depend on. Accepts a comma-separated
list of container reference names,
container titles, or container IDs.
Use it when several containers share
one model and you want to promote
just one of them — unlike
--models-with-deps, the other
containers on that model are left
alone. Brings the content in the
selected containers, the content it
links to, the containers holding
that linked content, the models
behind all of it, and the assets and
galleries it points at. No pages,
templates or URL redirections are
touched. The resolved scope is
printed before anything is written.
Cannot be combined with --models,
--models-with-deps or --pages.
[string] [default: ""]
--preflight, --pre-flight, --Preflight, Preflight mode (sync/push only): run
--PREFLIGHT, --PreFlight the full source-pull, target-pull,
dependency analysis and change
detection, then report the
creates/updates/skips/conflicts that
a real sync would produce — WITHOUT
writing anything to the target
instance or mapping files. Exits
non-zero if conflicts are detected.
[boolean] [default: false]
--fullPull, --full-pull, --FullPull, Discard the stored content sync
--FULLPULL token for every locale and re-pull
all content items and pages from
scratch, removing local content/page
files that no longer exist on the
instance. Use when a local cache is
suspected stale (e.g. copied or
renamed from another instance).
Models, containers, templates,
galleries and assets reconcile
against the instance on every pull
regardless.
[boolean] [default: false]
--jsonSummary, --json-summary, (sync/push only) Write a
--jsonsummary, --JsonSummary, machine-readable JSON summary of the
--JSONSUMMARY run to this path: per-phase
success/failure/skip counts, failure
and warning details, the exit
signal, and the preflight plan when
--preflight is used. Intended for CI
assertions and test harnesses;
parent directories are created, and
a write failure warns rather than
failing the run.
[string] [default: ""]
--sourceGuid, --source-guid, The source Agility instance GUID —
--sourceguid, --source, --SourceGuid, the instance you pull from (and the
--SourceGUID, --SOURCE, --SOURCEGUID source for a sync). Required for
pull and sync; falls back to
AGILITY_GUID from your .env file
when omitted. [string]
--targetGuid, --target-guid, The target Agility instance GUID —
--targetguid, --target, --TargetGuid, the instance you push/sync to.
--TargetGUID, --TARGET, --TARGETGUID Required for sync and push; falls
back to AGILITY_TARGET_GUID from
your .env file when omitted.[string]
--overwrite, --Overwrite, --OVERWRITE (sync only) Override target safety
conflicts. By default, a target item
that has its own changes conflicting
with the source is skipped to
prevent data loss; with --overwrite
those conflicting items are
overwritten with the source version.
Non-conflicting updates are applied
either way. Default: false.
[boolean] [default: false]
--autoPublish, --auto-publish, (sync only) After the sync
--AutoPublish, --AUTO_PUBLISH, completes, automatically publish
--autopublish items that were published in the
source instance. Accepts 'content'
(content items only), 'pages' (pages
only), or 'both'. Providing the flag
with no value defaults to 'both';
omit the flag to leave synced items
unpublished. [string]