Configuring the CloudFormation CLI Tools for Mac OS X

To prepare the install location

1. Open a Terminal window by doing one of the following:

   • Open the Launchpad (on Mac OS X Lion), open the Utilities folder, and click Terminal.

   • Open Finder, navigate to Applications / Utilities, and double-click Terminal.

2. In your terminal window, create the installation directory by typing:

   $ mkdir ~/.awstools

   This will create a hidden directory (if it doesn't already exist) called ".awstools" in your home directory.

To install the CLI tools

1. Change your working directory to ~/.awstools. You can do this on the command-line with:

   $ cd ~/.awstools

2. Unzip the downloaded AWSCloudFormation-cli.zip file in the install location, by typing:

   $ unzip ~/Downloads/AWSCloudFormation-cli.zip

   This will create a directory called AWSCloudFormation-#.#.#, where each # represents part of the version number.

3. (Optional) Link to the install directory, by typing:

   $ ln -s AWSCloudFormation-#.#.# cfn

   Again, the three # characters represent part of the version number, so to make the link to version 1.0.11 of the tools, type:

   $ ln -s AWSCloudFormation-1.0.11 cfn

   This enables you to easily install and switch to a new version of the tools, while allowing you to switch back to an older version just as easily. Simply overwrite the link with a new one.

To add your AWS credentials to the AWS credential file

1. Go to the AWS CloudFormation CLI tools install directory from the command-line, using:

   $ cd ~/.awstools/cfn

   This assumes that you installed the CLI tools into ~/.awstools and either linked or renamed the AWSCloudFormation-#.#.# directory to ~/.awstools/cfn. If you did not, replace this location in the example above with the pathname to the location where you installed the CLI tools.

2. Copy or rename the credential-file-path.template file to a filename of your choosing (you can even use credential-file-path.template as the filename, but I prefer something that better describes its purpose). For the purposes of this article, we'll use "myAWSCredentials.txt":

   $ cp credential-file-path.template myAWSCredentials.txt

3. Edit the file with your favorite text editor, enter your AWS credentials, then save and close the file. The file should contain two lines in it, like this:

   AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
   AWSSecretKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

   Note: These are example values, and won't work for an actual connection to AWS. Instead, use your own AWS security credentials here.

To add the CloudFormation CLI tools environment variables:

1. Edit ~/.profile in your favorite editor. If it does not exist yet, create it.

2. In ~/.profile, add the following lines:

   # CloudFormation CLI tools setup
   export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Home/"
   export AWS_CLOUDFORMATION_HOME="$HOME/.awstools/cfn"
   export AWS_CREDENTIAL_FILE="$AWS_CLOUDFORMATION_HOME/myAWSCredentials.txt"
   export PATH="$PATH:$AWS_CLOUDFORMATION_HOME/bin"

   This assumes that you installed the CLI tools into ~/.awstools and have either linked or renamed the AWSCloudFormation-#.#.# directory to ~/.awstools/cfn. If you did not, replace this location (where $HOME represents "~") with the pathname to the location where you installed the CLI tools.

   If you did not add your AWS access keys to an external file (such as the myAWSCredentials.txt file specified above), you should not assign the AWS_CREDENTIAL_FILE environment variable. Instead, remove or comment-out that line.

3. To load your environment variables, either quit and restart Terminal or, at the command-line prompt, type:

   $ source ~/.profile

4. Test your installation by running cfn-cmd:

   $ cfn-cmd

   This will list all of the available CloudFormation CLI tools, their usage, and the available options for cfn-cmd itself (there are two options: help and version).