# 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 Installation is available (and recommended) via Ruby Gems. ```bash $ gem install acquia_toolbelt ``` Once installed, the toolbelt is accessible via invoking `acquia` within the command line. ## Usage You can see all available commands by running `acquia help`. Additonally, more information on each command is available via `acquia [COMMAND] help`. ```bash $ acquia help Type 'acquia [COMMAND] help' for more details on subcommands or to show example usage. Commands: acquia auth acquia databases acquia deploy acquia domains acquia environments acquia files acquia servers acquia sites acquia ssh acquia svn acquia tasks Options: -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: ```bash $ acquia databases:list +------------------------+ | Name | +------------------------+ | acquiatoolbeltdev | | example-db | | newer-db | +------------------------+ ``` With parameters: ```bash $ 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! ## FAQ **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: ```bash $ export HTTPS_PROXY="http://myproxy.url.internal:1234" ``` Then to check the value was correctly set: ```bash $ echo $HTTPS_PROXY $ 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](https://github.com/jacobbednarz/acquia-toolbelt/wiki/Commands) in the [wiki](https://github.com/jacobbednarz/acquia-toolbelt/wiki). ## Hacking on the Acquia Toolbelt The Acquia Toolbelt uses [VCR](https://github.com/vcr/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](https://github.com/rspec/rspec). To run the test suite, execute the `script/test` script in the root of the repository: ```bash $ 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](https://travis-ci.org/jacobbednarz/acquia-toolbelt) 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.