AWS Documentation » AWS Identity and Access Management » CLI Reference » Getting the Command Line Tools	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Getting the Command Line Tools

To use the commands in this guide, you must get the command line interface (CLI). The interface is written in Java and includes shell scripts for both Windows and Linux/UNIX/Mac OSX.

You must have a Java SDK or JRE installed (version 1.6.x or later).

As a convention, all command line text in this guide is prefixed with a generic PROMPT> command line prompt. The actual command line prompt on your machine is likely to be different.

The CLI depends on three environment variables and a change to your system path. This section presents detailed steps for downloading the CLI and configuring your system to use it.

Note

Linux and Windows environment variables are reset whenever you close the command window. You might want to set your environment variables permanently. Consult the documentation for your version of Linux or Windows for more information on setting environment variables.

Note

The command line interface contains template files you can use to specify settings for AWS_CREDENTIAL_FILE and CLIENT_CONFIG_FILE. The templates are available at $AWS_IAM_HOME/aws-credential.template and $AWS_IAM_HOME/client-config.template, respectively.

Windows Users

Paths that contain a space must be wrapped in quotation marks, for example: "C:\Program Files\Java".

Downloading the CLI

To download the CLI

Go to IAM Command Line Toolkit and click Download.
Save the file.
Extract the contents.

Installing and Configuring Java

The IAM CLI requires either a Java Development Kit (SDK) or a Java Runtime Environment (JRE). If you don't already have one, or have a version older than 1.6, download the latest version from the Java SE Downloads page.

After you download and install the Java SDK or JRE, you must create an environmental variable that points to where Java is installed.

To set the JAVA_HOME variable

Enter the path to the Java installation:
- On Linux/UNIX, enter the following command:
```
PROMPT> export JAVA_HOME=<path_to_your_Java_installation>
```
- On Windows, enter the following command:
```
PROMPT> set JAVA_HOME=<path_to_your_Java_installation>
```

Confirm that the variable is set:

On Linux/UNIX, enter the following command:
```
PROMPT> ${JAVA_HOME}/bin/java -version
```
On Windows, enter the following command:
```
PROMPT> %JAVA_HOME%\bin\java -version
```

You will see output similar to the following:

java version "1.6.0_21"
Java(TM) SE Runtime Environment (build 1.6.0_21-b07)
Java HotSpot(TM) Client VM (build 17.0-b17, mixed mode, sharing)

Setting Up the CLI

After you download and unzip the IAM CLI, you must create a variable for the location of the IAM CLI, and you must include IAM in your path.

To set the AWS_IAM_HOME environment variable

On Linux/UNIX, enter the following command:
```
PROMPT> export AWS_IAM_HOME=<path_to_cli>
```
On Windows, enter the following command:
```
PROMPT> set AWS_IAM_HOME=<path_to_cli>
```

To include IAM in your path

On Linux/UNIX, enter the following command:

PROMPT> export PATH=$AWS_IAM_HOME/bin:$PATH

On Windows, enter the following command:

PROMPT> set Path=%AWS_IAM_HOME%\bin;%Path%

Setting Up the Credentials File

You need to provide the CLI with the AWS Access Key ID and Secret Access Key for your AWS account. The CLI looks for these credentials in a file you create on your local system.

Tip

If you are the AWS account owner, you can get your AWS account's credentials by going to the AWS Security Credentials page. After you sign in, you can find the access keys located in the Access Credentials section of the page.

If you are a user under an AWS account, you can get your AWS security credentials from your account administrator.

To create the credential file

Use a text editor to create a text file that contains two lines: the first line lists the AWS Access Key ID, and the second line lists the Secret Access Key. For example:
```
AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
AWSSecretKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
Save the file with any name you want (e.g., account-key).
Limit the file permissions to only the file owner (e.g., use chmod 600 on the file if you're using Linux/UNIX).

Caution

Your Secret Access Key is a secret that only you and AWS (or your system administrator) should know. It is important to keep it confidential to protect your account. Store it securely in a safe place. Never include it in your requests to AWS, and never email it to anyone. Do not share it outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your Secret Access Key.

After you set up the credentials file, you'll need to set the AWS_CREDENTIAL_FILE environment variable so that the CLI knows where to find your credentials.

To set the AWS_CREDENTIAL_FILE environment variable

Enter the path to the credentials file:

On Linux/UNIX, enter following command:

PROMPT> export AWS_CREDENTIAL_FILE=<path_and_filename_of_credential_file>

On Windows, enter the following command:

PROMPT> set AWS_CREDENTIAL_FILE=<path_and_filename_of_credential_file>

Run one of the commands in help mode to verify that your setup works properly:

PROMPT> iam-usercreate -h

You should see the help for the iam-usercreate command, which looks similar to this:

Creates a new user in your account. You can also optionally add the user
to one or more groups, and create an access key for the user.
iam-usercreate [options...] arguments...

 --aws-credential-file CREDENTIALFILE : path to the file containing your AWS credentials
 -d (--debug)                         : enable debug logging
 -g GROUPS                            : add user to group(s)
 -h                                   : print out this message
 -k                                   : create a key for the user
 -p PATH                              : the path of the user, defaults to /
 -u USERNAME                          : the name of the user
 -v VERBOSE                           : print out the newly created user's arn and guid

Setting Up the Proxy Configuration File

If your connection uses a proxy server (this is not common), you need to provide the CLI with the proxy settings. If you do not use a proxy server, then you can skip this step.

If you use a proxy server, the CLI looks for these configuration settings in a file you create on your local system.

To create the configuration file

Use a text editor to create a text file that contains the following lines:

ClientProxyHost=<your proxy server name>
ClientProxyPort=<your proxy server port number>
ClientProxyUsername=<your proxy user name>
ClientProxyPassword=<your proxy password>

Save the file with any name you want (e.g., myconfig.txt).
Limit the file permissions to only the file owner (e.g., use chmod 600 on the file if you're using Linux/UNIX).

After you set up the configuration file, you'll need to set the CLIENT_CONFIG_FILE environment variable so that the CLI knows where to find your proxy settings.

To set the CLIENT_CONFIG_FILE environment variable

On Linux/UNIX, enter following command:

PROMPT> export CLIENT_CONFIG_FILE=<path_and_filename_of_configuration_file>

On Windows, enter the following command:

PROMPT> set CLIENT_CONFIG_FILE=<path_and_filename_of_configuration_file>

You're now ready to use the IAM command line interface.

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...