Troubleshooting Acquia CLI

Use when:

• Diagnosing acli authentication failures
• Resolving command errors or unexpected output
• Collecting information before contacting support

General Issues

"Command not found: acli"

Cause: The binary isn't in your system PATH.

Solutions:

# Check if it's installed
which acli

# If nothing, add to PATH
export PATH="/usr/local/bin:$PATH"

# Test
acli --version

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Permission denied" when running acli

Cause: The binary isn't executable.

Solution:

chmod +x /usr/local/bin/acli
acli --version

"acli: command not found" after updating

Cause: Update didn't complete or PATH changed.

Solution:

# Reinstall
curl -fsSL https://github.com/acquia/cli/releases/latest/download/acli \
  -o /usr/local/bin/acli
chmod +x /usr/local/bin/acli

# Verify
acli --version

Authentication Issues

"Error: Failed to authenticate"

Cause: Your authentication token expired or isn't valid.

Solution:

# Re-authenticate
acli auth:login

# This opens your browser to authorize again

"Error: Access Denied"

Cause: Your account doesn't have permission to access the resource.

Solutions:

1. Check you're logged in with the right account:

   acli auth:me

1. Verify you have access in Acquia Cloud UI:

• Go to https://cloud.acquia.com
• Check if you can see the application or resource

1. Log out and back in:

   acli auth:logout
   acli auth:login

"Invalid JSON in credentials.json"

Cause: Credentials file is corrupted.

Solution:

# Remove the corrupted file
rm -rf ~/.acquia/cloud_api/

# Re-authenticate
acli auth:login

IDE Issues

IDE won't start

Symptoms: IDE shows "Starting..." indefinitely or won't load.

Solutions:

1. Try restarting IDE services:

   acli ide:service-stop
   acli ide:service-start

1. Check IDE status:

   acli ide:info

1. Wait if newly created:

New IDEs take 2-3 minutes to start. Check again in a minute.

1. Try creating a new IDE:

   acli ide:create

IDE is very slow

Causes: Hibernation waking, stuck processes, or resource limits

Solutions:

1. Wait if waking from hibernation:

IDEs waking take 30-60 seconds. Be patient.

1. Clear Drupal caches:

   acli remote:drush cr

1. Restart IDE:

   acli ide:service-restart

1. Create a fresh IDE:

   acli ide:create --label "Fresh IDE"

"Access Denied" when opening IDE

Cause: Your SSH key isn't set up.

Solution:

# Create an SSH key
acli ssh-key:create

# Try accessing IDE again
acli ide:open

IDE appears deleted but still exists

Cause: The IDE is hibernated or the listing is cached.

Solution:

# Clear cache and list again
acli self:clear-caches
acli ide:list

SSH Key Issues

"Permission denied (publickey)"

Cause: SSH key isn't set up or not used correctly.

Solutions:

1. Verify SSH key exists:

   ls -la ~/.ssh/id_rsa

1. If not, create one:

   acli ssh-key:create

1. Check permissions (must be 600):

   chmod 600 ~/.ssh/id_rsa

1. Verify key is added to Acquia account:

   acli ssh-key:list

"SSH key not found when creating IDE"

Cause: IDE creation requires an SSH key for secure access.

Solution:

# Create SSH key first
acli ssh-key:create

# Then create IDE
acli ide:create

"Multiple SSH keys - which one to use?"

Solution:

Add to ~/.ssh/config:

Host ide-*.ides.acquia.com
  IdentityFile ~/.ssh/my_custom_key

Application & Environment Issues

"No applications found"

Cause: You don't have access to any applications yet.

Solutions:

1. Check if you're in a team:

   acli auth:me

1. Ask your team admin to add you to an application

"Error: Application not found"

Cause: Wrong application UUID or no access.

Solutions:

1. List applications to find the right one:

   acli api:applications:list

1. Use the correct application:

   acli ide:create --application=<correct-uuid>

Command Execution Issues

"Error: Drush command failed"

Cause: Drush error in your Drupal site.

Solutions:

1. Check Drush output for details:

   acli remote:drush status

1. Clear caches:

   acli remote:drush cr

"Error: Could not connect to remote server"

Cause: Network connectivity or SSH key issue.

Solutions:

1. Check SSH key setup:

   acli ssh-key:list

1. Try verbose output for details:

   acli -vvv <command>

Performance Issues

Commands taking too long

Solutions:

1. Try again (might be temporary)

1. Check internet connection:

   ping acquia.com

1. Try with shorter timeout:

   acli <command> --no-wait

Cache causing stale data

Cause: CLI caches API responses.

Solutions:

# Clear cache
acli self:clear-caches   # aliases: acli cc, acli cr

# Try the command again
acli <command>

# Or run with --no-cache if supported
acli <command> --no-cache

Getting Help

Check your acli version

acli --version

Enable debug output

# Run any command with verbose output
acli -vvv <command>

# Save to a log file
acli -vvv <command> > debug.log 2>&1

View all help

# General help
acli --help

# List all commands
acli list

# Help for a specific command
acli <command> --help

Getting Help from Support

Before contacting support, gather info

# Your version
acli --version

# Your account info
acli auth:me

# Your applications
acli api:applications:list

# Your IDEs
acli ide:list

# Your SSH keys
acli ssh-key:list

# Debug output of the problem command
acli -vvv <command> 2>&1 | tee debug.log

Contact Acquia Support

• Support Portal: https://acquia.my.site.com/s/
• GitHub Issues: https://github.com/acquia/cli/issues
• Discussions: https://github.com/acquia/cli/discussions

Common Error Messages

Advanced Troubleshooting

Check API responses

# See what the API is returning
acli -vvv <command> 2>&1 | grep -A 5 "Response:"

Reset all configuration

# CAUTION: This clears everything
rm -rf ~/.acquia

# Re-authenticate
acli auth:login

Best Practices

1. Stay updated — Run acli self:update regularly; many errors are fixed in newer versions.
2. Check authentication first — Run acli auth:me before blaming other commands.
3. Use verbose mode — Add -vvv to any failing command to see detailed error output.

Still stuck? Contact Acquia Support