acli commands

acliv4.0.0

Lookup material for acli, Acquia’s Cloud Platform CLI. For task-oriented instructions, see the CLI quickstart and everyday workflows; for choosing between acli and other CLIs, see Which CLI do I use?. acli <command> --help is the exhaustive per-command source.

Find a command by task

I want to…	Commands	Guide
Install acli and authenticate	auth:login	CLI quickstart
Point acli at the right app and environment	app:link, remote:aliases:list	Everyday workflows
Tail logs from an environment	app:log:tail	Everyday workflows
Copy a database or files to local	pull:database, pull:files	Everyday workflows
Run Drush remotely or open a shell	remote:drush, remote:ssh	Everyday workflows
Deploy code as a build artifact	push:artifact	Everyday workflows
See which branch or tag each environment has deployed	app:vcs:info	Code-workflow quickstart
Switch an environment’s code, or roll production back	api:environments:code-switch	Code-workflow guide
Back up or restore an environment’s database	api:environments:database-backup-create, api:environments:database-backup-restore	Code-workflow guide
Create scheduled jobs, or copy them between environments	api:environments:cron-create, env:cron-copy	Run scheduled jobs
Create or delete a temporary environment	env:create, env:delete, app:task-wait	Everyday workflows
Authenticate in scripts and CI	auth:login with environment variables	Everyday workflows
Wrap a command with extra build steps	Composer hook points	Everyday workflows
Set up Code Studio	codestudio:wizard	Code Studio
Create a Cloud IDE	ide:create	Acquia’s Cloud IDE documentation
Decide between acli, drush, and the other CLIs	—	Which CLI do I use?

Global flags

Every command accepts these flags in addition to its own; an entry below with no flag table of its own takes only these. All flags are boolean toggles, default off, taking no value:

Flag	Description
-h, --help	Display help for the given command. When no command is given, display help for the list command
-q, --quiet	Do not output any message
-V, --version	Display the application version
--ansi / --no-ansi	Force (or disable) ANSI output
-n, --no-interaction	Do not ask any interactive question
-v, -vv, -vvv, --verbose	Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug

--verbose is the first tool for troubleshooting: most acli error messages become diagnosable when the command is re-run with it.

Exit codes

acli follows console conventions: 0 on success, 1 on any failure (API errors, invalid arguments, aborted operations). The exceptions are the two ways of waiting on a platform task: app:task-wait, and any api:* command run with --task-wait. Both report the awaited task’s outcome rather than whether the request itself was accepted.

Authenticate

The auth namespace registers and removes API credentials.

Command	What it does
auth:acsf-login	Register Site Factory API credentials; prompts for any omitted value
auth:acsf-logout	Remove Site Factory API credentials
auth:logout (alias logout)	Remove Cloud Platform API credentials

auth:login

Register Cloud Platform API credentials. acli can store multiple credential sets; only one is active at a time, and this command activates a new or existing set (see Credentials file). Alias: login.

acli auth:login [-k <key>] [-s <secret>]

Flag	Type	Default	Description
-k, --key	string	—	Your Cloud Platform API key. Prompts when omitted
-s, --secret	string	—	Your Cloud Platform API secret. Prompts when omitted

The first run on a machine also asks a one-time telemetry question:

$ acli auth:login
No Cloud Platform API key is active
You will need a Cloud Platform API token from https://cloud.acquia.com/a/profile/tokens

 Do you want to open this page to generate a token now? (yes/no) [yes]:
 >
[INFO] Opening https://cloud.acquia.com/a/profile/tokens

The non-interactive form acli auth:login --key=<key> --secret=<secret> saves and activates the credentials directly, confirming with The following Cloud Platform API key is active: <account email> (captured).

Used in: CLI quickstart, non-interactive auth.

Applications and projects

The app and archive namespaces: link your working directory to a Cloud Platform application, inspect it, scaffold new projects, and export the whole thing.

Command	What it does
app:new:from:drupal7 (aliases from:d7, ama)	Generate a Drupal 9+ project from a Drupal 7 application using the default Acquia Migrate Accelerate recommendations
app:new:local (alias new)	Create a new Drupal or Next.js project from a template
app:open (aliases open, o)	Open the application in the Cloud Platform user interface
app:vcs:info	List the application’s branches and tags with their deployment status; --deployed narrows it to the ones an environment is running (used in the code-workflow quickstart)
archive:export	Export an archive of the Drupal application including code, files, and database

app:link

Associate your project with a Cloud Platform application: writes cloud_app_uuid to .acquia-cli.yml (see Project link file). Alias: link.

acli app:link [<applicationUuid>]

applicationUuid (optional): the application UUID or alias (an application name optionally prefixed with the realm, the hosting cluster identifier shown alongside the application name in acli api:applications:find output, e.g. myapp or prod:myapp). Prompts interactively when omitted.

Example (captured 2026-07-06, identifiers redacted):

$ acli app:link myapp
 [OK] The Cloud application myapp has been linked to this repository by writing to /path/to/project/.acquia-cli.yml

Used in: Everyday workflows.

app:log:tail

Tail the logs from your environments. Prompts for which logs to stream, then streams until interrupted. Aliases: tail, log:tail.

acli app:log:tail [<environmentId>]

environmentId (optional): the environment ID or alias (myapp.dev, prod:myapp.dev, or a UUID). Prompts interactively when omitted.

Each line is the log record as the platform wrote it, unprefixed and in that log type’s own format; the types you pick at the prompt decide which records appear. Nothing is printed between requests, so a quiet environment shows the header and then waits.

Example (captured 2026-08-03, two of the streamed lines, identifiers and addresses redacted):

$ acli app:log:tail myapp.dev
Streaming has started and new logs will appear below. Use Ctrl+C to exit.
127.0.0.1 - - [03/Aug/2026:10:07:46 +0000] "GET /?docs-capture=1 HTTP/1.1" 200 1001 "-" "curl/8.14.1" status=200 bytes=1001 http_host=myappdev.prod.acquia-sites.com affinity="-" upstream_addr="<ip>:443" hosting_site=myappdev request_time=0.017 forwarded_for="<client-ip>" upstream_status="200" request_id="v-<uuid>" ssl_protocol="-" ssl_cipher="-"
127.0.0.1 - - [03/Aug/2026:10:07:50 +0000] "GET /?docs-capture=2 HTTP/1.1" 200 1001 "-" "curl/8.14.1" status=200 bytes=1001 http_host=myappdev.prod.acquia-sites.com affinity="-" upstream_addr="<ip>:443" hosting_site=myappdev request_time=0.011 forwarded_for="<client-ip>" upstream_status="200" request_id="v-<uuid>" ssl_protocol="-" ssl_cipher="-"

Used in: Everyday workflows.

app:task-wait

Wait for a task to complete.

acli app:task-wait <notification-uuid>

notification-uuid (required): a task notification UUID, or a Cloud Platform API JSON response containing a linked notification (the JSON must contain the _links->notification->href property).

Exit codes: 0 if the awaited task completes successfully, 1 if the task fails; this is the one command whose exit code reports more than command success.

The command prints the task’s final record after the wait: progress, completion time, task type, and how long it took.

Example (captured 2026-08-03, UUIDs redacted):

$ acli app:task-wait "$(acli api:environments:database-backup-create myapp.dev my_db)"
    ✔ Waiting for task <uuid> to complete

 [OK] The task with notification uuid <uuid> completed


Progress: 100
Completed: Mon Aug 3 13:21:47 EEST 2026
Task type: Database backup created
Duration: 30 seconds

Used in: Everyday workflows.

app:unlink

Remove the local association between your project and a Cloud Platform application; operates on the current directory’s .acquia-cli.yml. Alias: unlink.

acli app:unlink

Example (captured 2026-07-06, identifiers redacted):

$ acli app:unlink
Unlinked /path/to/project from Cloud application myapp

Used in: Everyday workflows.

Pull from an environment

All pull:* commands accept an optional environmentId argument (ID or alias such as myapp.dev; prompts when omitted) and a --siteInstanceId flag (string, the Site Instance ID in the form SITEID.EnvironmentID). All of them except pull:code also accept an optional site argument: for a multisite application, the directory name of the site.

Command	What it does
pull:code	Copy code from a Cloud Platform environment
pull:run-scripts	Execute post-pull scripts

pull:all

Copy code, database, and files from a Cloud Platform environment. Aliases: refresh, pull.

acli pull:all [<environmentId>] [<site>] [options]

Flag	Type	Default	Description
--dir	string	—	The directory containing the Drupal project to be refreshed
--no-code	boolean	false	Skip copying code
--no-files	boolean	false	Skip copying files
--no-databases	boolean	false	Skip copying databases
--no-scripts	boolean	false	Do not run additional scripts after code and database are copied (e.g. composer install, drush cache-rebuild)

The code step is a git fetch --all followed by git checkout <the environment's branch> in the local repository, so it aborts on uncommitted changes rather than overwriting them. When the database step prints its backup-age notice, acli redraws over the completed code line, so the finished run shows the file, database, and script steps but not the code step it already ran.

Example (captured 2026-08-03, identifiers redacted):

$ acli pull myapp.dev default
    ✔ Copying Drupal's public files from the Cloud Platform
        Connecting to database db


 [INFO] Using a database backup that is 4 hours old. Backup #355275600 was created at Mon Aug 3 9:16:09 EEST 2026.

        You can view your backups here: https://cloud.acquia.com/a/environments/<environment-id>/databases

        To generate a new backup, re-run this command with the --on-demand option.


    ✔ Downloading my_db database copy from the Cloud Platform
    ✔ Importing my_db database download
 ! [NOTE] Composer dependencies already installed. Skipping composer install.

Used in: Everyday workflows.

pull:database

Import a database backup from a Cloud Platform environment. Uses the latest available database backup, which may be up to 24 hours old; if no backup exists, one is created. Requires an active local database connection: set ACLI_DB_HOST, ACLI_DB_NAME, ACLI_DB_USER, ACLI_DB_PASSWORD (see environment variables). Alias: pull:db.

acli pull:database [<environmentId>] [<site>] [options]

Flag	Type	Default	Description
--no-scripts	boolean	false	Do not run additional scripts after the database is pulled (e.g. drush cache-rebuild, drush sql-sanitize)
--on-demand	boolean	false	Force creation of an on-demand backup (much slower than using an existing backup)
--no-import	boolean	false	Download the backup but do not import it (implies --no-scripts)
--multiple-dbs	boolean	false	Download multiple databases

The backup’s age is reported before the download, with the console link to the environment’s backup list and the reminder that --on-demand forces a fresh one. Import drops the local database’s tables first, so the local database is replaced rather than merged. acli pull:db myapp.prod --no-import stops after the download.

Example (captured 2026-08-03, identifiers redacted):

$ acli pull:database myapp.dev --no-scripts

 [INFO] Using a database backup that is 4 hours old. Backup #355275600 was created at Mon Aug 3 9:16:09 EEST 2026.

        You can view your backups here: https://cloud.acquia.com/a/environments/<environment-id>/databases

        To generate a new backup, re-run this command with the --on-demand option.


    ✔ Downloading my_db database copy from the Cloud Platform
    ✔ Importing my_db database download

Used in: Everyday workflows.

pull:files

Copy Drupal public files from a Cloud Platform environment to your local environment.

acli pull:files [<environmentId>] [<site>]

The transfer is an rsync over SSH into docroot/sites/<site>/files, so it is incremental: a second run copies only what changed.

Example (captured 2026-08-03, identifiers redacted):

$ acli pull:files myapp.dev default
    ✔ Copying Drupal's public files from the Cloud Platform

Used in: Everyday workflows.

Push to an environment

Every push:* command accepts the same --siteInstanceId flag as its pull:* counterpart (string, SITEID.EnvironmentID).

There is no working push:code command; code deployment through acli is artifact-based via push:artifact. (A hidden push:code stub is unhidden inside a Cloud IDE or a Lando environment. It only prints Use git to push code changes upstream. and exits 0.)

push:artifact

Build and push a code artifact to a Cloud Platform environment. Builds a sanitized deploy artifact by running composer install, removing sensitive files, and committing vendor directories and scaffold files, even if they are ignored in the source repository. Designed for the two-branch scenario: a source branch without vendor files committed and an artifact branch with them; if both are the same branch, use plain git push instead. To run additional build or sanitization steps (e.g. npm install), add a post-install-cmd script to composer.json. Aborts if the local repository has uncommitted changes (Pushing code was aborted because your local Git repository has uncommitted changes. Either commit, reset, or stash your changes via git.).

acli push:artifact [<environmentId>] [options]

Flag	Type	Default	Description
--dir	string	—	The directory containing the Drupal project to be pushed
--no-sanitize	boolean	false	Do not sanitize the build artifact
--no-push	boolean	false	Do not push changes to Acquia Cloud
--no-commit	boolean	false	Do not commit changes (implies --no-push)
--no-clone	boolean	false	Do not clone the repository (implies --no-commit and --no-push)
-u, --destination-git-urls	array of string	—	The git URL(s) to push the artifact branch to (repeatable)
-b, --destination-git-branch	string	—	The destination branch
-t, --destination-git-tag	string	—	The destination tag (requires --destination-git-branch)
--siteInstanceId	string	—	The Site Instance ID (SITEID.EnvironmentID)

--dry-run and -s, --source-git-tag are deprecated. Defaults may also come from the ACLI_PUSH_ARTIFACT_* environment variables.

The run opens with a note listing exactly what it is about to do, including the git remote it will push to, so the destination is visible before anything is written. When --destination-git-branch names a branch that does not exist upstream yet, the fetch for it fails and acli creates the branch locally instead, then pushes it as a new branch. Passing --destination-git-branch also makes the environmentId argument unnecessary: the argument is only read to work out the destination branch from the environment’s deployed VCS path.

Example (captured 2026-08-03, identifiers redacted):

$ acli push:artifact --destination-git-branch=docs-capture-build

 ! [NOTE] Acquia CLI will:
 !
 !        - git clone docs-capture-build from
 !        myapp@svn-<id>.prod.hosting.acquia.com:myapp.git
 !
 !        - Compile the contents of /path/to/project into an artifact in a
 !        temporary directory
 !
 !        - Copy the artifact files into the checked out copy of
 !        docs-capture-build
 !
 !        - Commit changes and push the docs-capture-build branch to the
 !        following git remote(s):
 !
 !          myapp@svn-<id>.prod.hosting.acquia.com:myapp.git

    ✔ Preparing artifact directory
    ✔ Generating build artifact
    ✔ Sanitizing build artifact
    ✔ Committing changes (commit hash: 654564fd504bc60851694ef31995c21126fd4cb8)
    ✔ Pushing changes to docs-capture-build branch.

Used in: Everyday workflows.

push:database

Push a database from your local environment to a Cloud Platform environment. Destructive on the target: run the pre-flight check first. Alias: push:db.

acli push:database [<environmentId>] [<site>]

The confirmation names the target database and environment before anything is written, and defaults to yes, so an unattended run overwrites. The three steps are a local mysqldump, an rsync of the compressed dump to the environment, and an import over SSH; the local connection comes from the ACLI_DB_* environment variables.

Example (captured 2026-08-03, identifiers redacted):

$ acli push:database myapp.dev

 Overwrite the my_db database on dev with a copy of the database from the current machine? (yes/no) [yes]:
 > yes

    ✔ Creating local database dump
    ✔ Uploading database dump to remote machine
    ✔ Importing database dump into MySQL on remote machine

Used in: Migrate an existing site.

push:files

Copy Drupal public files from your local environment to a Cloud Platform environment, overwriting the target’s files.

acli push:files [<environmentId>] [<site>]

Like its pull: counterpart the transfer is an rsync, so it adds and updates rather than mirroring: files that exist only on the environment stay. Omit the site argument and the command prompts for the site directory.

Example (captured 2026-08-03, identifiers redacted):

$ acli push:files myapp.dev default

 Overwrite the public files directory on dev with a copy of the files from the current machine? (yes/no) [yes]:
 > yes

    ✔ Pushing public files directory to remote machine

Used in: Migrate an existing site.

Manage environments

The env namespace creates, deletes, and reshapes environments.

Command	What it does
env:certificate-create	Install an SSL certificate
env:cron-copy	Copy all cron tasks from one environment to another (used in scheduled jobs)

env:create

Create a new Continuous Delivery Environment (CDE).

acli env:create <label> [<branch>] [<applicationUuid>]

label (required): the label of the new environment; branch (optional): the VCS path (git branch name) to deploy to the new environment; applicationUuid (optional).

The branch must already exist on the remote VCS: the command rejects a name it cannot find, rather than creating it.

The label is a display name, not an address. The environment’s alias is myapp.ode<n>, numbered in creation order across the application’s lifetime, and the domain is that same pair with the dot removed. The pr-123 environment below is myapp.ode2, reachable at myappode2.prod.acquia-sites.com. Take the alias from the command’s own URL line or from remote:aliases:list, never from the label.

Example (captured 2026-08-03, identifiers redacted):

$ acli env:create pr-123 master
    ✔ Checking to see that label is unique
    ✔ Determining default database
    ✔ Initiating environment creation
    ✔ Waiting for the environment to be ready. This usually takes 2 - 15 minutes.

Your CDE URL: myappode2.prod.acquia-sites.com

A subscription’s CDE allowance is finite. When it is used up the command fails at the third step, on the Cloud Platform API’s own error rather than a local check, so the first two steps still report success:

$ acli env:create docs2 master
    ✔ Checking to see that label is unique
    ✔ Determining default database
    ⌛ Initiating environment creation...


In ExceptionListener.php line 120:

  Cloud Platform API returned an error: This application already has the maxi
  mum number of CD environments.

Delete an existing CDE with env:delete and retry.

Used in: Everyday workflows.

env:delete

Delete a Continuous Delivery Environment (CDE).

acli env:delete [<environmentId>]

environmentId (optional): environment ID or alias. Omit it and the command lists the application’s CDEs by label and prompts; that list is the reliable way to find a CDE’s alias, because the alias is myapp.ode<n> and not the label passed to env:create.

The command returns as soon as the platform accepts the request: the environment is deleted in the background, so the confirmation is phrased as “is being deleted” rather than “deleted”.

Example (captured 2026-08-03, identifiers redacted):

$ acli env:delete myapp.ode2

 [OK] The pr-123 environment is being deleted

Used in: Everyday workflows.

env:mirror

Makes one environment identical to another in terms of code, database, files, and configuration. Destructive on the destination: run the pre-flight check first.

acli env:mirror <source-environment> <destination-environment> [options]

source-environment, destination-environment (required): environment IDs or aliases.

Flag	Type	Default	Description
-c, --no-code	boolean	false	Skip mirroring code
-d, --no-databases	boolean	false	Skip mirroring databases
-f, --no-files	boolean	false	Skip mirroring files
-p, --no-config	boolean	false	Skip mirroring configuration

All four copies are started first and awaited afterwards, so they run concurrently on the platform and the command’s wall-clock time is the slowest of them rather than their sum. Each one is a platform task, reported the same way app:task-wait reports one. The code step is a branch switch to the source environment’s deployed branch, not a code copy, so mirroring between two environments already on the same branch leaves the code untouched. The confirmation defaults to yes.

Example (captured 2026-08-03, identifiers and UUIDs redacted):

$ acli env:mirror myapp.test myapp.dev
    ✔ Fetching information about source environment
    ✔ Fetching information about destination environment

 Are you sure that you want to overwrite everything on Dev (dev) and replace it with source data from Stage (test) (yes/no) [yes]:
    ✔ Initiating code switch
    ✔ Initiating database copy
    ✔ Initiating files copy
    ✔ Initiating config copy
    ✔ Waiting for code copy to complete



 [OK] The task with notification uuid <uuid> completed


Progress: 100
Completed: Mon Aug 3 13:25:47 EEST 2026
Task type: Code switched
Duration: 16 seconds
    ✔ Waiting for database copy to complete


 [OK] The task with notification uuid <uuid> completed


Progress: 100
Completed: Mon Aug 3 13:28:03 EEST 2026
Task type: Database copied
Duration: 147 seconds
    ✔ Waiting for files copy to complete


 [OK] The task with notification uuid <uuid> completed


Progress: 100
Completed: Mon Aug 3 13:26:37 EEST 2026
Task type: Files copied
Duration: 55 seconds
    ✔ Waiting for config copy to complete


 [OK] The task with notification uuid <uuid> completed


Progress: 100
Completed: Mon Aug 3 13:27:54 EEST 2026
Task type: Environment configuration updated
Duration: 126 seconds


 [OK] Done! Dev now matches Stage

      You can visit it here:

      https://myappdev.prod.acquia-sites.com

SSH, remote Drush, and aliases

The remote namespace runs things on your environments over SSH and manages the Drush aliases that address them.

remote:aliases:download

Download Drush aliases for the Cloud Platform.

acli remote:aliases:download [<applicationUuid>] [options]

Flag	Type	Default	Description
--destination-dir	string	—	The directory to which aliases will be downloaded
--all	boolean	false	Download the aliases for all applications you have access to, not just the current one

Example (captured 2026-07-06, identifiers redacted):

$ acli remote:aliases:download myapp --destination-dir=/path/to/aliases
Drush changed how aliases are defined in Drush 9. Drush 8 aliases are PHP-based and stored in your home directory, while Drush 9+ aliases are YAML-based and stored with your project.
Cloud Platform Drush aliases installed into /path/to/aliases

Used in: code workflow section.

remote:aliases:list

List all aliases for the Cloud Platform environments. Prompts for the application when the UUID is omitted. Aliases: aliases, sa.

The suffix in an alias is the environment’s name, not the label on its environment card. The environment labeled Stage is named test, so its alias is myapp.test. acli matches the suffix against those names exactly, so myapp.stage resolves nothing and every command that takes an alias fails on it.

acli remote:aliases:list [<applicationUuid>]

Example (hostnames redacted):

$ acli remote:aliases:list myapp
+------------+---------------------------------------------+--------------------------------+
| Alias      | UUID                                        | SSH URL                        |
+------------+---------------------------------------------+--------------------------------+
| myapp.dev  | 146125-04f18e5e-3e19-4698-ac58-c162df025345 | myapp.dev@…ssh.prod.acquia-sites.com  |
| myapp.prod | 146123-04f18e5e-3e19-4698-ac58-c162df025345 | myapp.prod@…ssh.prod.acquia-sites.com |
| myapp.test | 146124-04f18e5e-3e19-4698-ac58-c162df025345 | myapp.test@…ssh.prod.acquia-sites.com |
+------------+---------------------------------------------+--------------------------------+
Run acli api:environments:find <alias> to get more information about a specific environment.

Used in: Everyday workflows.

remote:drush

Run a Drush command (Drupal’s own application-level CLI; see Which CLI do I use?) remotely on a Cloud Platform environment. Note the -- separating the acli arguments from the Drush command and its options; it is required. Aliases: drush, dr.

acli remote:drush [<environmentId>] -- <drush_command>

environmentId (optional); drush_command: the Drush command, after --.

The Drush that runs is the environment’s own, resolved from the deployed codebase, and its output comes back unaltered: acli adds nothing to it. Everything the report names (database host, PHP binary, Drupal root) is the environment’s, which is what makes status the fastest way to confirm a deploy landed.

Example (captured 2026-08-03, credentials and identifiers redacted):

$ acli remote:drush myapp.dev -- status
Drupal version   : 11.2.5
Site URI         : http://myappdev.prod.acquia-sites.com
DB driver        : mysql
DB hostname      : db-<id>.cdb.database.services.acquia.io
DB port          : 3306
DB username      : <db-user>
DB name          : <db-name>
Database         : Connected
Drupal bootstrap : Successful
Default theme    : olivero
Admin theme      : claro
PHP binary       : /usr/local/php8.3/bin/php
PHP config       : /usr/local/php8.3/etc/cli/php.ini
PHP OS           : Linux
PHP version      : 8.3.31
Drush script     : /var/www/html/vendor/bin/drush.php
Drush version    : 13.6.2.0
Drush temp       : /tmp
Drush configs    : /etc/drush/drush.yml
                   /var/www/html/vendor/drush/drush/drush.yml
Install profile  : standard
Drupal root      : /var/www/html/docroot
Site path        : sites/default
Files, Public    : sites/default/files
Files, Private   : /mnt/files/myapp.dev/sites/default/files-private
Files, Temp      : /tmp
Drupal config    : ../config/default

Used in: Everyday workflows, Which CLI do I use?.

remote:ssh

Use SSH to open a shell or run a command in a Cloud Platform environment. Requires an SSH key registered with the platform (ssh-key:create-upload). Alias: ssh.

acli remote:ssh <alias> [-- <ssh_command>]

alias (required): application and environment in the format app-name.env; ssh_command (optional): command to run via SSH; opens a shell in the site directory when omitted.

Exit codes: 0 success, 1 failure, or the remote command’s own exit code.

The shell opens in the environment’s site directory: the repository checkout under docroot/, the acquia-files symlink into the environment’s network filesystem, and two symlinks named after the environment that point back at the same directory. Most of it is read-only to the SSH user, which is why file changes go through push:files rather than an interactive session.

Example (captured 2026-08-03, identifiers redacted):

$ acli remote:ssh myapp.dev -- ls -al
total 580
dr-xr-sr-x.  1 myapp.dev myapp   4096 Aug  3 10:29 .
drwxrwxrwx.  4 root      root    4096 Aug  3 10:29 ..
-r--r--r--.  1 myapp.dev myapp     53 Aug  3 10:28 .acquia-cli.yml
lrwxrwxrwx.  1 root      myapp     22 Aug  3 10:29 acquia-files -> /mnt/gfs/myappdev
-r--r--r--.  1 myapp.dev myapp   4404 Aug  3 10:28 composer.json
-r--r--r--.  1 myapp.dev myapp 489333 Aug  3 10:28 composer.lock
dr-xr-sr-x.  3 myapp.dev myapp   4096 Aug  3 10:28 config
dr-xr-s---.  1 myapp.dev myapp   4096 Aug  3 10:29 docroot
lrwxrwxrwx.  1 root      myapp     13 Aug  3 10:29 myapp.dev -> /var/www/html
lrwxrwxrwx.  1 root      myapp     13 Aug  3 10:29 myappdev -> /var/www/html
dr-xr-sr-x.  3 myapp.dev myapp   4096 Aug  3 10:28 files-private
-r--r--r--.  1 myapp.dev myapp   1726 Aug  3 10:28 .gitignore
-r--r--r--.  1 myapp.dev myapp  18092 Aug  3 10:28 LICENSE
-r--r--r--.  1 myapp.dev myapp    835 Aug  3 10:28 phpcs.xml.dist
-r--r--r--.  1 myapp.dev myapp    159 Aug  3 10:28 phpstan.neon.dist
-r--r--r--.  1 myapp.dev myapp    658 Aug  3 10:28 phpunit.xml.dist
-r--r--r--.  1 myapp.dev myapp   2949 Aug  3 10:28 README.md
dr-xr-sr-x.  2 myapp.dev myapp   4096 Aug  3 10:28 recipes
-r--r--r--.  1 myapp.dev myapp     56 Aug  3 10:28 salt.txt
-r--r--r--.  1 myapp.dev myapp    460 Aug  3 10:28 SECURITY.md
dr-xr-sr-x.  3 myapp.dev myapp   4096 Aug  3 10:28 tests
dr-xr-sr-x. 39 myapp.dev myapp   4096 Aug  3 10:28 vendor

Used in: Everyday workflows.

SSH keys

The ssh-key namespace manages the keys that authorize SSH access to your environments.

Command	What it does
ssh-key:create	Create an SSH key on your local machine
ssh-key:delete	Delete an SSH key
ssh-key:info	Print information about an SSH key
ssh-key:list	List your local and Cloud Platform SSH keys, matched by fingerprint
ssh-key:upload	Upload a local public SSH key to the Cloud Platform

ssh-key:create-upload

Create an SSH key on your local machine and upload it to the Cloud Platform. Prompts for anything omitted.

acli ssh-key:create-upload [options]

Flag	Type	Default	Description
--filename	string	—	The filename of the SSH key
--password	string	—	The password for the SSH key
--label	string	—	The SSH key label to be used with the Cloud Platform
--no-wait	boolean	false	Don’t wait for the SSH key to be uploaded to the Cloud Platform

Uploading is instant; installing the key across the application’s servers is not. Unless --no-wait is passed, the command polls three groups of hosts (git, non-production, production) by trying to connect, and returns when all three answer. The warning quotes an hour as the worst case; the run below finished in under two minutes. The key is added to the local SSH agent along the way, so no ssh-add follows.

Example (captured 2026-08-03, identifiers redacted):

$ acli ssh-key:create-upload --filename=id_rsa_acli --password=<password> --label=laptop

 ! [NOTE] It may take an hour or more before the SSH key is installed on all of your application's servers. Create a
 !        Support ticket for further assistance.

 Would you like to wait until your key is installed on all of your application's servers? (yes/no) [yes]:
    ✔ Waiting for the key to become available in Cloud Platform git environments
    ✔ Waiting for the key to become available in Cloud Platform nonprod environments
    ✔ Waiting for the key to become available in Cloud Platform prod environments

Your SSH key is ready for use!




 [OK] Uploaded id_rsa_acli to the Cloud Platform with label laptop

While the polling runs, the connection attempts that have not yet succeeded print Permission denied (publickey) for each host. Those lines are the wait working, not a failure.

Used in: Everyday workflows.

Cloud IDEs

The ide namespace manages Cloud IDEs. Commands marked IDE-only exist only when run inside a Cloud IDE: hidden from acli list outside an IDE in 4.0.0, but still invocable and documented by --help. Adding a Cloud IDE to a subscription, creating one, and its resource limits are on Acquia’s Cloud IDE documentation.

Command	What it does
ide:create	Create a Cloud IDE
ide:delete	Delete a Cloud IDE
ide:info	Print information about a Cloud IDE
ide:list:app (alias ide:list)	List the Cloud IDEs belonging to an application
ide:list:mine	List the Cloud IDEs belonging to you
ide:open	Open a Cloud IDE in your browser
ide:php-version	Change the PHP version in the current IDE (IDE-only)
ide:service-restart	Restart php, apache, or mysql (IDE-only)
ide:service-start	Start php, apache, or mysql (IDE-only)
ide:service-stop	Stop php, apache, or mysql (IDE-only)
ide:share	Get the share URL for a Cloud IDE (IDE-only)
ide:wizard:ssh-key:create-upload (alias ide:wizard)	Wizard for first-time setup tasks within an IDE (IDE-only)
ide:wizard:ssh-key:delete	Wizard to delete the IDE’s SSH key from Cloud (IDE-only)
ide:xdebug-toggle (alias xdebug)	Toggle Xdebug on or off in the current IDE (IDE-only)

Code Studio

The codestudio namespace configures Code Studio projects.

Command	What it does
codestudio:php-version	Change the PHP version in Code Studio

codestudio:wizard

Create and/or configure a new Code Studio project for a given Cloud Platform application. Prompts for anything omitted. Alias: cs:wizard.

acli codestudio:wizard [<applicationUuid>] [<codebaseId>] [options]

applicationUuid (optional); codebaseId (optional): the Cloud Platform codebase ID.

Flag	Type	Default	Description
--key	string	—	The Cloud Platform API token that Code Studio will use
--secret	string	—	The Cloud Platform API secret that Code Studio will use
--gitlab-token	string	—	The GitLab personal access token used to communicate with the GitLab instance
--gitlab-project-id	integer	—	The project ID of the GitLab project to configure
--gitlab-host-name	string	—	The GitLab hostname

Prerequisite: the GitLab CLI (glab) must be on your PATH, because the wizard reads the GitLab host and token out of glab’s own configuration. Each lookup has an opt-out (--gitlab-host-name for the host, --gitlab-token for the token), so passing both is what lets the command run on a machine without glab. Passing neither stops the run at the host lookup, before the Cloud Platform is contacted at all.

Example (captured 2026-08-03, on a machine without glab):

$ acli cs:wizard

In CodeStudioCommandTrait.php line 79:

  Install glab to continue: https://gitlab.com/gitlab-org/cli#installation


codestudio:wizard [--key KEY] [--secret SECRET] [--gitlab-token GITLAB-TOKEN] [--gitlab-project-id GITLAB-PROJECT-ID] [--gitlab-host-name GITLAB-HOST-NAME] [--]
 [<applicationUuid> [<codebaseId>]]



 [help] You can find Acquia CLI documentation at https://docs.acquia.com/acquia-cli/

        You can submit a support ticket at https://support-acquia.force.com/s/contactsupport
        Re-run the command with the -vvv flag and include the full command output in your support ticket.

Used in: CI/CD section, Which CLI do I use?

codestudio:pipelines-migrate

Migrate an .acquia-pipeline.yml file to a .gitlab-ci.yml file for a given Acquia Cloud application. IDE-only (hidden outside Cloud IDEs; excluded from the official generated command docs). Alias: cs:pipelines-migrate.

acli codestudio:pipelines-migrate [<applicationUuid>] [options]

Flag	Type	Default	Description
--key	string	—	The Cloud Platform API token that Code Studio will use
--secret	string	—	The Cloud Platform API secret that Code Studio will use
--gitlab-token	string	—	The GitLab personal access token used to communicate with the GitLab instance
--gitlab-project-id	integer	—	The project ID of the GitLab project to configure

It shares codestudio:wizard’s glab prerequisite but carries no --gitlab-host-name flag to opt out of the host lookup, so glab is required here even when --gitlab-token is supplied.

Example (captured 2026-08-03, on a machine without glab):

$ acli cs:pipelines-migrate

In CodeStudioCommandTrait.php line 79:

  Install glab to continue: https://gitlab.com/gitlab-org/cli#installation


codestudio:pipelines-migrate [--key KEY] [--secret SECRET] [--gitlab-token GITLAB-TOKEN] [--gitlab-project-id GITLAB-PROJECT-ID] [--] [<applicationUuid>]



 [help] You can find Acquia CLI documentation at https://docs.acquia.com/acquia-cli/

        You can submit a support ticket at https://support-acquia.force.com/s/contactsupport
        Re-run the command with the -vvv flag and include the full command output in your support ticket.

Used in: Which CLI do I use?

Site Factory

The acsf namespace works like the Cloud Platform API namespace: 107 generated commands (at 4.0.0, unchanged since 2.61.3) matching the bundled Site Factory API spec, hidden from acli list, each named acsf:<resource>:<action> and documented by its own --help. Authenticate first with auth:acsf-login.

Command	What it does
acsf:list (alias acsf)	List all Site Factory commands
acsf:<resource>	Each resource is also its own lister command: acli acsf:sites lists every sites command

The Cloud Platform API

acli api:* commands match the Cloud Platform API, endpoint for endpoint, following the API specifications bundled with each release: assets/acquia-spec.json for the v2 API, and, new in 4.0.0, assets/acquia-v3-spec.json for the v3 API, whose commands sit under api:v3:*. Each API endpoint has a command named api:<resource>:<action> (v3: api:v3:<resource>:<action>); its arguments are the endpoint’s path parameters and its flags are the endpoint’s request parameters. Output is always the endpoint’s machine-readable JSON response: pipe it to jq to filter (see orientation).

These 477 commands (at 4.0.0: 345 matching the v2 API, unchanged from 3.0.1, plus 132 matching v3) span every Cloud Platform API resource, from accounts and applications to environments, codebases, and subscriptions. They are hidden from acli list: discover them with acli api:list (after authenticating with auth:login) and inspect any one of them with --help. For per-command documentation, the tool itself is the source of truth (acli api:<command> --help), alongside the per-command pages published from the same source under Acquia CLI commands on docs.acquia.com.

Command	What it does
api:list (alias api)	List all API commands
api:<resource>	Each resource is also its own lister command: acli api:environments lists every environments command
list api:v3	List every api:v3:* command. acli api:list shows the v3 surface as one row, api:v3:v3, and that command only prints the v3 namespaces, so acli list api:v3 (or acli list api:v3:<resource>) is the listing that works

Most api:v3:* commands carry a stability tag at the end of their description ([development], for example); running one whose stability is not production also prints a warning that the command may change without notice.

A generated command with real output:

acli api:applications:environment-list myapp | jq '.[].name'

"dev"
"prod"
"test"

Applications with Remote Administration or AMA entitlements list additional environments (ra, ama) here.

The unfiltered response is the Cloud Platform API’s JSON, field names unchanged; the glossary uses those same names.

Waiting for a task to finish

Many platform operations are asynchronous: the endpoint accepts the request, returns 202 with a linked notification, and the work happens in the background. Every generated command whose endpoint can answer 202 carries one extra flag, 151 commands in 4.0.0 (the same 93 v2 commands as in 3.0.1, plus 58 under api:v3:*):

Flag	Type	Default	Description
--task-wait	boolean	false	Wait for this task to complete

Without it, the command prints the JSON response and exits as soon as the request is accepted. With it, the command reads the notification out of that response, blocks until the task settles, and exits 0 only if the task succeeded (1 if it failed), which is the same contract as app:task-wait. Reach for --task-wait when the operation is a single step in a script, and for app:task-wait when you need to keep the JSON response or wait on a task started elsewhere.

acli api:<command> --help tells you whether a given command has the flag; the read-only ones (api:applications:list, api:environments:find) don’t.

Used in: CLI quickstart (api:applications:list), everyday workflows (api:applications:environment-list), its temporary environments job (api:environments:database-backup-create), stale content (api:environments:clear-caches with --task-wait), the code-workflow quickstart (api:environments:find for the repository URL), the code-workflow guide’s rollback runbook (api:environments:code-switch, api:environments:database-backup-list, api:environments:database-backup-restore), scheduled jobs (api:environments:cron-create, api:environments:cron-job-list), per-environment settings (api:environments:update, api:environments:variable-create), and what the platform logs (api:environments:log-list, api:environments:log-download).

Maintain acli itself

The top-level commands and the self namespace: help, discovery, updates, caches, and telemetry.

Command	What it does
docs	Open Acquia product documentation in the browser
help	Display help for a command (same as <command> --help)
list (alias self:list)	List commands, optionally for one namespace
completion	Dump the shell completion script for your shell
self:clear-caches (aliases cc, cr)	Clear local Acquia CLI caches
self:info	Print version, build date, config paths, and telemetry status
self:telemetry:disable (alias telemetry:disable)	Disable anonymous sharing of usage and performance data
self:telemetry:enable (alias telemetry:enable)	Enable anonymous sharing of usage and performance data
self:telemetry:toggle (alias telemetry)	Toggle anonymous sharing of usage and performance data

If acli itself fails to boot because of a stale kernel cache, the pseudo-command acli clear-kernel-cache (ckc) clears it before the application starts. Telemetry can also be disabled with the ACLI_NO_TELEMETRY=true environment variable.

self-update

Update acli to the latest release. The canonical name is self:update; self-update and update are its aliases.

acli self-update [--stable] [--preview] [--compatible] [<version_constraint>]

version_constraint (optional): a version constraint limiting which release is installed, for pinning an update to a range instead of taking whatever is newest.

Flag	Type	Default	Description
--stable	boolean	false	Use stable releases. This is already what happens when no flag is passed
--preview	boolean	false	Preview unstable releases (alpha, beta, and so on)
--compatible	boolean	false	Stay on the current major version

--compatible is the flag to reach for when a major release lands and you are not ready for it: it takes the newest release that shares your current major version. version_constraint does the same job more precisely.

When the installed binary is already the newest matching release, the command says so and exits 0:

$ acli self-update
No update available

Otherwise the update writes a temp file next to the acli binary, so it fails when that directory isn’t writable by your user:

$ acli self-update
acli update failed: the "/usr/local/bin" directory used to download the temp file could not be written

Re-run with sudo acli self-update, or update through whatever originally installed acli.

Used in: Everyday workflows (version mismatch fix).

Configuration

Credentials file

acli auth:login stores Cloud Platform API credentials in cloud_api.conf inside the acli config directory:

• ~/.acquia/ if that directory exists (the default on machines that have run acli or other Acquia tooling before),
• otherwise $XDG_CONFIG_HOME/acquia/,
• otherwise ~/.config/acquia/.

Multiple credential sets can be stored; one is active at a time, switched with auth:login.

Project link file

app:link writes the linked application UUID to .acquia-cli.yml (key: cloud_app_uuid) in the project root. Commands run inside that directory use the linked application when no applicationUuid argument is given.

Environment variables

Variable	Effect
ACLI_ACCESS_TOKEN	Cloud Platform API access token. Highest-priority credential source
ACLI_ACCESS_TOKEN_EXPIRY	Expiry timestamp for ACLI_ACCESS_TOKEN; required alongside it
ACLI_ACCESS_TOKEN_FILE / ACLI_ACCESS_TOKEN_EXPIRY_FILE	Read the token/expiry from a file instead of the variable
ACLI_KEY / ACLI_SECRET	Cloud Platform API key and secret. Second-priority credential source, after the access token and before cloud_api.conf
ACLI_DB_HOST, ACLI_DB_NAME, ACLI_DB_USER, ACLI_DB_PASSWORD	Local database connection used by pull:*/push:* database commands. Preset by recommended local stacks such as Lando
ACLI_PUSH_ARTIFACT_DESTINATION_GIT_URLS	Default destination git URLs for push:artifact
ACLI_PUSH_ARTIFACT_DESTINATION_GIT_BRANCH	Default destination branch for push:artifact
ACLI_PUSH_ARTIFACT_DESTINATION_GIT_TAG / ACLI_PUSH_ARTIFACT_SOURCE_GIT_TAG	Default destination/source tags for push:artifact
ACLI_PUSH_ARTIFACT_COMMIT_MSG	Commit message used for the artifact commit
ACLI_NO_TELEMETRY	Set to true to disable telemetry
ACLI_CLOUD_API_BASE_URI / ACLI_CLOUD_API_V3_BASE_URI / ACLI_CLOUD_API_ACCOUNTS_URI	Override the Cloud Platform API v2, API v3 (default https://api.acquia.com/v3; acli 4.0.0+), and accounts endpoints
ACLI_HOME	Override the config/data directory
AH_ORGANIZATION_UUID	Workaround for federated-authentication failures; see the note below

Credential precedence, highest first: ACLI_ACCESS_TOKEN (+ expiry) → ACLI_KEY/ACLI_SECRET → cloud_api.conf. Non-interactive auth shows this in use.

Federated authentication: if a command fails with This resource requires additional authentication, set AH_ORGANIZATION_UUID to your organization UUID (from the URL at https://cloud.acquia.com/a/organizations/<organization-UUID>), then re-run acli auth:login. Requires acli 2.14.0+.

Composer hook points

Any command can be wrapped with Composer scripts named pre-acli-<command> / post-acli-<command>, where <command> is the command name with dashes instead of colons (pre-acli-push-db, post-acli-pull-files). See hook scripts.

Used in

• CLI quickstart: install, authenticate, and run a first command.
• Everyday CLI workflows: the task-shaped recipes each command entry backs.
• Which CLI do I use?: where acli stops and pipelines, drush, gh, and glab start.
• Code workflow guide: deploys, database copies, and backup restores.
• Set up a codebase: app:link and the Acquia git remote.
• Migrate an existing codebase: alias downloads and the ACLI_DB_* variables.
• Scheduled jobs: the generated api:* commands and --task-wait.