Quickstart

Goal: run one real acli command against the Cloud Platform from your terminal.

What you’ll have when you’re done

• acli installed as a standalone executable at /usr/local/bin/acli.
• Cloud Platform API credentials stored in cloud_api.conf inside acli’s config directory (~/.acquia/ if it exists, otherwise ~/.config/acquia/).
• One successful command (acli api:applications:list) printing real JSON from your account.

Prerequisites

• A Cloud Platform application you can access, or a free trial
• curl (preinstalled on macOS and Linux)
• PHP 8.2 or later with the json and Phar extensions enabled. acli refuses to start on anything older, with This application requires a PHP version matching "^8.2" (the requirement is the same in acli 3.x and 4.x). php --version checks the version; php -m lists enabled extensions and should include both. Both extensions ship enabled in standard PHP builds.

No PHP on this machine?

If php --version answers command not found: php, Docker can supply the runtime, and the official php image already has json and Phar enabled. Step 1 below still applies: download the Phar. Steps 2 and 3 do not, because the Phar stays in the directory you mount instead of moving into your PATH.

Mounting ~/.acquia as well puts the credentials acli auth:login writes on your machine, where a system PHP would have put them, rather than inside a container that --rm throws away:

mkdir -p ~/.acquia
docker run --rm -it \
  -v "$PWD":/app -w /app \
  -v "$HOME/.acquia":/root/.acquia \
  php:8.3-cli php acli.phar auth:login

Run it from a directory under your home directory: that path is shared with containers by every runtime’s default configuration. A $PWD outside the shared paths (easy to hit on Colima) mounts as an empty directory, and the only symptom is Could not open input file: acli.phar.

Every command on this page then runs the same way: keep the docker run prefix and swap auth:login for the command you want. php acli.phar --version prints Acquia CLI 4.0.0 from inside the container, the same build a system PHP runs.

A DDEV project’s web container carries PHP as well, so ddev exec php acli.phar api:applications:list runs the Phar from the project directory. Authentication is the exception: acli auth:login writes into that container’s home directory, which ddev restart rebuilds, so the credentials have to be entered again after every restart. The docker run form above keeps them in ~/.acquia on your machine instead.

For PHP on the machine itself, the php.net install docs cover every platform.

Steps

1. Download the Phar

   acli is distributed as a standalone Phar archive (a single-file PHP executable, like a .jar for PHP). Download the latest release:

   curl -OL \
     https://github.com/acquia/cli/releases/latest/download/acli.phar

   Do not install acli with Composer. Installing it as a Composer dependency can create dependency conflicts with your project; the Phar is the supported install.

2. Make it executable

   chmod +x acli.phar

3. Move it into your PATH

   Rename the file and move it to a globally accessible location so you can type acli from anywhere. If the command fails, prefix it with sudo:

   mv acli.phar /usr/local/bin/acli

   Verify the install from any directory: acli --version prints the installed version (plain acli also lists every available command):

   acli --version

   Acquia CLI 4.0.0

4. Authenticate with the Cloud Platform API

   acli auth:login

   The command walks you through creating a Cloud Platform API token at cloud.acquia.com/a/profile/tokens: open that page, select Create Token, give it a label like acli, and copy the API key and API secret it shows. This API token is not the site API client from the auth quickstart: they are separate credential systems, and pasting a client ID/secret here fails.

   Paste the API key and secret at the prompts:

   acli auth:login session

   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]:
    >
   Please enter your API Key: <ENTER API KEY HERE>
   Please enter your API Secret: <ENTER API SECRET HERE>
   Saved credentials to /home/<user>/.acquia/cloud_api.conf

   That last line is the whole outcome: your token is now stored in ~/.acquia/cloud_api.conf, and every future acli command reads it from there.

5. Run your first real command

   List the applications your account can access:

   acli api:applications:list

   A successful response is a JSON array with one entry per application (one real entry shown here):

   [
     {
       "id": 990066,
       "uuid": "04f18e5e-3e19-4698-ac58-c162df025345",
       "name": "Brewtal",
       "hosting": {
         "type": "ace",
         "id": "prod:eeschandan1"
       },
       "subscription": {
         "uuid": "840f74b5-bf16-4e70-baf1-49c40bbaed35",
         "name": "Brewtal"
       },
       "organization": {
         "uuid": "870bd8d4-e53a-41a8-ab05-1057fd43a5c7",
         "name": "Brewtal Org"
       },
       "flags": {
         "remote_admin": false
       },
       "status": "normal",
       "type": "drupal",
       "_links": {
         "self": {
           "href": "https://cloud.acquia.com/api/applications/04f18e5e-3e19-4698-ac58-c162df025345"
         },
         "parent": {
           "href": "https://cloud.acquia.com/api/applications"
         }
       },
       "_embedded": {
         "tags": []
       }
     }
   ]

   What to look at:

   • uuid: the application’s unique ID. Any command that takes an applicationUuid argument accepts this value.
   • name: the application’s display name (here Brewtal).
   • hosting.id: the hosting realm and sitegroup (prod:eeschandan1). The sitegroup portion (eeschandan1) is the application alias that commands accept as shorthand for the UUID; combined with an environment name it identifies an environment (eeschandan1.dev). The alias often matches name, but not always (as here), so when a command reports No applications match the alias, reach for the UUID or the sitegroup.
   • subscription: the subscription this application belongs to.
   • _links, _embedded: hypermedia the Cloud Platform API attaches to every resource; acli api:* passes the response through untouched.

   These field names aren’t invented for the CLI: acli api:* commands call the Cloud Platform API directly, so what you see here is the API’s own response, field names included. The glossary uses these names too: application UUID is this uuid.

What just happened

You installed a single self-contained executable (no Composer, no project dependency), exchanged a one-time login for an API token stored in ~/.acquia/cloud_api.conf, and made an authenticated call to the Cloud Platform API through its CLI mirror. Everything else acli does (tailing logs, pulling databases, deploying artifacts) uses this same stored credential.

When something goes wrong

command not found: acli

the Phar isn’t in your PATH. Confirm the move succeeded with ls -l /usr/local/bin/acli, and confirm /usr/local/bin is in your PATH with echo $PATH. If the mv in step 3 failed with Permission denied, re-run it with sudo.

PHP Fatal error: Uncaught Error: Class "Phar" not found

the PHP-PHAR extension is disabled. Enable the phar extension in your php.ini, then run acli again. acli also warns you at startup if any other runtime requirement is missing; follow the instructions in those messages.

Your requirements could not be resolved to an installable set of packages. after composer require acquia/cli

installing acli via Composer carries a documented risk of dependency conflicts with your application. Remove the Composer install (composer remove acquia/cli) and use the Phar from steps 1–3 instead.

Your Cloud Platform API credentials are invalid. (or a 403) after login

the key or secret was mistyped, or the token was revoked. Generate a fresh token at cloud.acquia.com/a/profile/tokens and run acli auth:login again; the new credentials replace the old ones in ~/.acquia/cloud_api.conf.

Next steps

• Register an SSH key before you touch code: acli ssh-key:create-upload generates one if you don’t have it and registers it with Acquia in a single command. Cloning an application’s repository and pushing to it both need one, so this is the step between an authenticated CLI and working with code.
• Set up local development: run the site on your machine in containers, with a Cloud Platform environment’s database and files.
• Everyday CLI workflows: the daily jobs: tail logs, pull databases, run Drush remotely, deploy artifacts.
• acli command reference: every command, flag, and configuration option.
• Which CLI do I use?: where acli ends and Pipelines CLI, drush, and the other tools begin.