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/Mac OSX.

To install the CloudWatch CLI

  1. Download the CLI from Amazon CloudWatch Command Line Tool.

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

  3. Type the command java -version to determine the version of Java installed. If you do not have version 1.5 or newer, download and install a newer version from

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


    Don't include the bin directory in JAVA_HOME or the CLI won't work.

    • [Linux] The following 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
    • [Windows] The following 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


      If you are using Cygwin, you must use Linux/UNIX paths (for example, /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.

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

    • [Linux] You can update your PATH as follows:

      $ export PATH=$PATH:$JAVA_HOME/bin 


      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.

    • [Windows] You an update your PATH as follows:

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


      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.

    • [Linux] You can check the version of Java as follows:

      $ $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)
    • [Windows] You can check the version of Java as follows:

      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.

    • [Linux] You can set this environment variable as follows:

      $ export AWS_CLOUDWATCH_HOME=<path-to-tools>  
    • [Windows] You can set this environment variable as follows:

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

    • [Linux] You can update your PATH as follows:

      $ export PATH=$PATH:$AWS_CLOUDWATCH_HOME/bin 
    • [Windows] You can update your PATH as follows:

      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 (for example, --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.

    • [Linux] Set the file permissions as follows:

      $ chmod 600 <credential file name>
    • [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.

    • [Linux] You can set this environment variable as follows:

      $ export AWS_CREDENTIAL_FILE=<path-to-file>  
    • [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 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.

    • [Linux] The following example sets AWS_CLOUDWATCH_URL to EU (Ireland).

      $ export AWS_CLOUDWATCH_URL=
    • [Windows] The following sets AWS_CLOUDWATCH_URL to EU (Ireland).

      C:\> set AWS_CLOUDWATCH_URL= 
      C:\> setx AWS_CLOUDWATCH_URL 

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. 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'