A CLI application for interacting with the Acquia Cloud API.
Ruby Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Acquia Toolbelt

The Acquia Toolbelt is a CLI tool for using the Acquia Cloud API. Some of the features include getting information around your servers, subscription, databases, tasks and domains.


Installation is available (and recommended) via Ruby Gems.

$ gem install acquia_toolbelt

Once installed, the toolbelt is accessible via invoking acquia within the command line.


You can see all available commands by running acquia help. Additonally, more information on each command is available via acquia [COMMAND] help.

$ acquia help

Type 'acquia [COMMAND] help' for more details on subcommands or to show example usage.

  acquia auth
  acquia databases
  acquia deploy
  acquia domains
  acquia environments
  acquia files
  acquia servers
  acquia sites
  acquia ssh
  acquia svn
  acquia tasks

  -s, [--subscription=SUBSCRIPTION]  # Name of a subscription you would like to target.
  -e, [--environment=ENVIRONMENT]    # Environment to target for commands.
  -v, [--verbose]                    # Increase the verbose output from the commands.

Example commands

Without parameters:

$ acquia databases:list

| Name                   |
| acquiatoolbeltdev      |
| example-db             |
| newer-db               |

With parameters:

$ acquia databases:list --environment=dev --database=acquiatoolbeltdev

| Name              | Username | Password        | Host      | DB cluster | Instance name        |
| acquiatoolbeltdev | s22614   | 7Ps5kU7s3VEvFTj | free-4422 | 3119       | acquiatoolbeltdevdev |

Getting started

Before you can start using any commands, you need to first run acquia auth:login. This will write your login details to a local netrc file so that you won't be prompted for login details every time a request is made. After that, the sky is the limit!


Q: Is there support for proxies and corporate firewalls?

A: By god yes. Proxies and corporate firewalls are the bane of my existence so there was no way this toolbelt wasn't going to support it. To use a proxy, all you need to do is set your HTTPS_PROXY environment variable to the required value. Example:

$ export HTTPS_PROXY="http://myproxy.url.internal:1234"

Then to check the value was correctly set:

$ http://myproxy.url.internal:1234

Q: Is there somewhere I can see all the commands with required parameters?

A: Yep. Check out the commands listing in the wiki.

Hacking on the Acquia Toolbelt

The Acquia Toolbelt uses VCR for recording and replaying API fixtures during test runs - doing this allows the tests to stay fast and easy for anyone to run.

Authenticated requests are currently using the user credentials from the netrc file on your local system. It is a good idea to have this setup first (simply by running acquia auth:login) as if you are recording new cassettes you will need to be able to make actual requests. Don't worry about your user credentials being stored in the fixtures as they are removed during the request and they will appear as ACQUIA_USERNAME and ACQUIA_PASSWORD in the requests respectively.

Since the cassettes are periodically refreshed to match changes to the API, remember the keep the following in mind when making cassettes.

  • Specs should be idempotent. The HTTP calls made during a spec should be able to be run over and over. This means deleting a known resource prior to creating it if the name has to be unique.
  • Specs should be able to be run in random order. If a spec depends on another resource as a fixture, make sure that's created in the scope of the spec and not depend on a previous spec to create the data needed.
  • Do not depend on authenticated user info. Instead of asserting actual values in resources, try to assert the existence of a key or that a response is an Array. We're testing the client, not the API.

Running and writing new tests

The testing is mainly done via RSpec. To run the test suite, execute the script/test script in the root of the repository:

$ script/test

This will ensure all dependencies are installed and kick off the test suite.

Supported versions

This library aims to support and is tested against the following Ruby implementations:

  • Ruby 1.9.2
  • Ruby 1.9.3
  • Ruby 2.0.0
  • Ruby 2.1.0

If you would like support for other implementations or versions, please open an issue and it can be looked into.