Menu
Amazon CloudWatch
Command Line Reference (API Version 2010-08-01)

Set Up the Command Line Interface

Before you can use the Amazon CloudWatch command line interface (CLI) with CloudWatch, you must install and configure the CLI.

Step 1: Install the CLI

The CLI is written in Java and includes shell scripts for both Windows and Linux/UNIX/Mac OSX.

To install the CloudWatch CLI

  1. Download the CLI from Amazon CloudWatch Tools.

  2. Save and unpack the CloudWatch archive to a convenient location on your workstation.

  3. Enter the command java -version to determine the version of Java installed on your workstation. If you do not have version 1.5 or newer, download and install a newer version from http://www.java.com.

  4. Set the JAVA_HOME environment variable to point to your Java installation.

    Note

    If you are using Cygwin, you must use Linux/UNIX paths (e.g., /usr/bin instead of C:\usr\bin) for AWS_CLOUDWATCH_HOME and AWS_CREDENTIAL_FILE. However, JAVA_HOME should have a Windows path. Additionally, the value cannot contain any spaces, even if the value is quoted or the spaces are escaped.

    • The following Linux/UNIX example shows how to set the JAVA_HOME for a Java executable in the /usr/local/jre/bin directory.

      $ export JAVA_HOME=/usr/local/jre
    • The following Windows example shows how to use the set and setx commands to set JAVA_HOME for a Java executable in the C:\java\jdk1.6.0_6\bin directory. The set command defines JAVA_HOME for the current session and setx makes the change permanent.

      C:\> set JAVA_HOME=C:\java\jdk1.6.0_6
      C:\> setx JAVA_HOME C:\java\jdk1.6.0_6

    Note

    Don't include the bin directory in JAVA_HOME; the CLI won't work if you do.

  5. Add your Java directory to your path before other versions of Java.

    • On Linux and UNIX, you can update your PATH as follows:

      $ export PATH=$PATH:$JAVA_HOME/bin 

      Note

      The export command applies only to the current shell session. To permanently create or update an environment variable, include the command in a start-up script. For example, if you use Bash shell, you can include commands in your ~/.bashrc or /etc/profile file.

    • On Windows, the syntax is slightly different:

      C:\> set PATH=%PATH%;%JAVA_HOME%\bin 

      Note

      The Windows environment variables are reset when you close the command window. You might want to set them permanently with the setx command.

  6. Verify your JAVA_HOME setting with the command $JAVA_HOME/bin/java -version.

    $ $JAVA_HOME/bin/java -version
            java version "1.6.0_33"
            Java(TM) SE Runtime Environment (build 1.6.0_33-b03)
            Java HotSpot(TM) Client VM (build 20.8-b03, mixed mode, sharing)

    The syntax is different on Windows, but the output is similar.

    C:\> %JAVA_HOME%\bin\java -version
            java version "1.6.0_33"
            Java(TM) SE Runtime Environment (build 1.6.0_33-b03)
            Java HotSpot(TM) Client VM (build 20.8-b03, mixed mode, sharing)
  7. The CLI depends on an environment variable (AWS_CLOUDWATCH_HOME) to locate supporting libraries. You'll need to set this environment variable to the location where you unpacked the CloudWatch archive.

    • On Linux and UNIX, you can set this environment variable as follows:

      $ export AWS_CLOUDWATCH_HOME=<path-to-tools>  
    • On Windows, the syntax is slightly different:

      C:\> set AWS_CLOUDWATCH_HOME=<path-to-tools>  
  8. Add the CLI bin directory to your system PATH environment variable.

    • On Linux and UNIX, you can update your PATH as follows:

      $ export PATH=$PATH:$AWS_CLOUDWATCH_HOME/bin 
    • On Windows, the syntax is slightly different:

      C:\> set PATH=%PATH%;%AWS_CLOUDWATCH_HOME%\bin 
      C:\> setx PATH %PATH%;%AWS_CLOUDWATCH_HOME%\bin 

Step 2: Configure the CLI for Your Credentials

You must provide your AWS credentials before you can use the CloudWatch CLI. There are two types of access keys: access key IDs and secret access keys. You should have stored your access keys in a safe place when you created them. Although you can retrieve your access key ID from the Your Security Credentials page, you can't retrieve your secret access key. Therefore, if you can't find your secret access key, you'll need to create new access keys before you can use the CLI tools.

You can either specify your credentials with the ––aws-credential-file parameter and include the full path to the credential file (e.g., --aws-credential-file=c:\my-aws-credentials.txt) every time you issue a command or you can create an environment variable that points to the credential file on your local system. If the environment variable is properly configured, you can omit the ––aws-credential-file parameter when you issue a command. The following procedure describes how to create a credential file and a corresponding AWS_CREDENTIAL_FILE environment variable.

To set up security credentials for the CLI

  1. Add your access key ID and secret access key to the file named credential-file-path.template, located in the folder where you installed the CloudWatch CLI.

  2. Rename the file and save it to a convenient location on your workstation.

    • If you are using Linux or UNIX, set the file permissions as follows:

      $ chmod 600 <credential file name>
    • On Windows, you do not need to change the file permissions.

  3. Set the AWS_CREDENTIAL_FILE environment variable to the fully-qualified path of the credential file you just created.

    • On Linux and UNIX, you can set this environment variable as follows:

      $ export AWS_CREDENTIAL_FILE=<path-to-file>  
    • On Windows, you can set this environment variable as follows:

      C:\> set AWS_CREDENTIAL_FILE=<path-to-file>  

Step 3: Set the Region

By default, the Amazon CloudWatch CLI uses the US East (N. Virginia) Region (us-east-1) with the monitoring.us-east-1.amazonaws.com service endpoint URL. If your instances are in a different region, you must specify the region where your instances reside. For example, if your instances are in Europe, you must specify the EU (Ireland) Region by using the ––region eu-west-1 parameter or by setting the AWS_CLOUDWATCH_URL environment variable.

This procedure describes how to specify a different region by changing the service endpoint URL.

To specify a different region

  1. To view available regions, see Regions and Endpoints in the Amazon Web Services General Reference.

  2. To change the service endpoint, set the AWS_CLOUDWATCH_URL environment variable.

    • The following Linux/UNIX example sets AWS_CLOUDWATCH_URL to the EU (Ireland) Region.

      $ export	AWS_CLOUDWATCH_URL=http://monitoring.eu-west-1.amazonaws.com/
    • The following Windows example sets AWS_CLOUDWATCH_URL to the EU (Ireland) Region.

      C:\> set AWS_CLOUDWATCH_URL=http://monitoring.eu-west-1.amazonaws.com/ 
      C:\> setx AWS_CLOUDWATCH_URL http://monitoring.eu-west-1.amazonaws.com/ 

Step 4: Test Your CLI Configuration

After you have installed and configured the CloudWatch CLI, you should test your configuration.

To test your CLI installation and configuration

  1. On your workstation, open a new command prompt.

  2. Type the command mon-cmd.

    You should see output similar to the following:

    Command Name                       Description                                            
            
            mon-delete-alarms                  Delete alarms      
            mon-describe-alarm-history         Describe alarm history  
            mon-describe-alarms                Describe alarms fully. 
            mon-describe-alarms-for-metric     Describe all alarms ... a single metric
            mon-disable-alarm-actions          Disable all actions for a given alarm
            mon-enable-alarm-actions           Enable all actions for a given alarm
            mon-get-stats                      Get metric statistics        
            mon-list-metrics                   List user's metrics      
            mon-put-data                       Put metric data 
            mon-put-metric-alarm               Create new alarm or update existing one
            mon-set-alarm-state                Manually set the state of an alarm
            mon-version                        Prints the version ... tool and the API 
            
            For help on a specific command, type '<commandname> ––help'