# Agility CLI Command Reference > Source: https://agilitycms.com/docs/developers/cli-reference 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. - For what a sync copies, how mappings work and how conflicts are handled, see [Agility CLI](/docs/developers/cli). - For running the CLI in a pipeline, see the [CLI CI/CD Integration Guide](/docs/developers/cli-ci-cd-integration-guide). ## Commands | Command | Aliases | What it does | Reference | | --- | --- | --- | --- | | `agility login` | | Signs in through the browser, or stores a Personal Access Token | [login and logout](/docs/developers/cli-login-logout) | | `agility logout` | | Removes the stored sign-in and any stored Personal Access Token | [login and logout](/docs/developers/cli-login-logout) | | `agility pull` | | Downloads an instance to local files | [pull](/docs/developers/cli-pull) | | `agility push` | `sync` | Copies one instance into another, with dependency resolution and mappings | [sync and push](/docs/developers/cli-sync) | | `agility reverse-sync` | | Copies changes from the target of an earlier sync back into its source | [reverse-sync](/docs/developers/cli-reverse-sync) | | `agility workflows` | `workflow` | Publishes, unpublishes, approves, declines or requests approval for synced items | [workflows](/docs/developers/cli-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`. ## Running the CLI 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: ```bash # 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`. > [!WARNING] > 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. ## Options shared by every command 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](/docs/developers/cli-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. ## Authentication 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=` 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: 1. `--token` on the command line. 2. `AGILITY_TOKEN`, from the environment or a `.env` file. If both set it, the `.env` file's value is used. 3. A PAT stored in the keychain by an earlier run. 4. A browser sign-in stored in the keychain. If none is stored, or it has expired, the browser sign-in starts. 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](/docs/developers/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. ## Configuration from .env files 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 | - Options on the command line take precedence over these files. - If more than one file sets the same key, the first file in the order above wins. - Lines that start with `#` are ignored. - The CLI also looks for `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. > [!IMPORTANT] > 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. ## Exit codes 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 | | > [!NOTE] > 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](/docs/developers/cli-sync#json-summary). ## Files the CLI writes 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. ```text 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](/docs/developers/cli). ## Help output The top-level help for 1.1.0, as printed by `npx @agility/cli@1.1.0 --help`: ```text 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] ```
The shared options, as printed by agility pull --help ```text agility 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] ```