Sync configuration with acli

Goal: export a Source CMS site’s configuration into a working copy with acli, change it, and import it back.

What you’ll have when you’re done

• The site’s configuration as YAML under .acquia/config, one file per configuration object.
• The site recorded in the working copy, so later commands need no site argument.
• An import that either applies the whole working copy or refuses with every violation listed.

Prerequisites

• A Source CMS site you hold site-administrator rights on. Organization administrators hold those rights today.
• acli installed and logged in. See the CLI quickstart.

Which command moves configuration which way

The commands are named from the working copy’s side, the way git is: pull brings the site’s configuration to you, push sends yours to the site.

What you run	Direction	What it does
acli source:cms:config:pull	Export	Writes the site’s configuration into .acquia/config, replacing what is there
acli source:cms:config:push	Import	Sends .acquia/config to the site, replacing the site’s configuration

An import takes the site offline and replaces its configuration.

Steps

1. Record the site in the working copy, or pass it on every command

   A command with no site refuses rather than guessing. Record the site once:

   acli source:cms:link <sourceSiteId>

   That writes source_site_id into .acquia-cli.yml; commit it. Run without an argument in a terminal, the command lists the sites you can reach. acli source:cms:unlink removes the record from the local file.

   Or pass the site on each command, which suits a pipeline deploying one branch to several sites. --site overrides a recorded site:

   acli source:cms:config:push --site=<sourceSiteId> --yes

   The site ID is the Acquia identifier of the site you connect to. It is not the site UUID inside the exported configuration, which the site checks on import.

2. Export the configuration into your working copy

   From your repository root:

   acli source:cms:config:pull

   The first export creates .acquia/config in the current directory, and later commands find it from any subdirectory. The layout is a Drupal configuration directory: one <name>.yml per object, with translation overrides under language/<langcode>/.

   An export replaces the whole directory without prompting. Uncommitted local edits are lost. Commit or stash before exporting, then rebase your work on top.

3. Import it back into the site

   acli source:cms:config:push --yes

   --yes skips the confirmation prompt; without it and without a terminal, the command refuses. The command waits for the import to finish, so its exit status is the import’s outcome.

   The site goes offline while an import runs. It enters maintenance mode, and a database backup and a configuration checkpoint are taken before anything is applied. Editors lose unsaved work. If the import fails, the site reverts to the checkpoint and comes back online.

4. Read the outcome

   A refusal exits non-zero. The command reports one of three outcomes:

   • Imported. The site holds what your working copy held.
   • Refused. Nothing was imported. The command lists every violation, not only the first.
   • Unknown. The command lost track of the import or hit its 45-minute ceiling. The import may still finish, so check the site before retrying.

   Add --format=json to print only the outcome, as JSON.

What just happened

You exported the site’s configuration to files and imported them back. acli only moves the files; the site runs every check, in one pass, against the whole change set:

• each object is in the synced configuration
• it matches its schema
• its dependencies resolve once the change set is applied
• the configuration came from this site

One violation refuses the whole import. Exports are not checked, so a site an import would refuse can still be exported, fixed, and imported back.

When something goes wrong

The import is refused because the site has drifted.

The site’s live configuration changed since the last sync, usually through a Drupal update. Export, commit what comes back, and import again.

The import is refused because the site has never been exported.

Run an export against that site before the first import.

The import is refused on the site UUID.

The configuration came from a different site. Environments of one site share a UUID; different sites do not, and configuration cannot be copied between them.

The import is refused naming a configuration object.

The object is outside the synced configuration or broke a rule. Fix every listed violation, then import again.

The import is refused for removing configuration that still holds content.

Removing a content type, vocabulary, media type, field, menu, workflow, or language that still has content is refused, and nothing is deleted. Delete the content first, then import the removal.

The import is refused for removing something other configuration depends on.

The refusal names the object and each dependent. Remove them together, or keep the object.

.acquia/config does not exist.

Run an export first, or run the command from inside the working copy.

Your local configuration edits disappeared.

An export replaced the directory. Recover them from version control.

The import is refused for a document that is too large.

An import accepts at most 1 MiB of configuration, and an export has no limit. Splitting the directory does not help, because an import sends it as one document. To raise the limit, contact Acquia Support.

Next steps

• Deploy configuration from CI/CD: run the import from a pipeline on every push.
• Canvas CLI reference: Canvas components, patterns, page regions, and content templates sync through Canvas CLI instead.