AWS Command Line Interface
User Guide

Tutorial: Using the AWS CLI to Deploy an Amazon EC2 Development Environment

This tutorial describes how to use the AWS Command Line Interface (AWS CLI) to set up a development environment in Amazon Elastic Compute Cloud (Amazon EC2). It includes a short version of the installation and configuration instructions. You can run it from start to finish on Windows, Linux, macOS, or Unix.

Step1: Install the AWS CLI

You can install the AWS CLI with an installer (Windows) or by using pip, a package manager for Python.


  1. Download the MSI installer.

  2. Run the downloaded MSI installer.

  3. Follow the instructions that appear.

Linux, macOS, or Unix

These steps require that you have a working installation of Python 2 version 2.6.5+ or Python 3 version 3.3+. If you encounter any issues using the following steps, see the full installation instructions in the AWS Command Line Interface User Guide.

  1. If you have pip installed, skip to step 2. If you don't have pip installed, download and run the installation script from the pip website.

    $ curl "" -o "" % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1622k 100 1622k 0 0 14.9M 0 --:--:-- --:--:-- --:--:-- 14.9M $ python3 --user Collecting pip Using cached Collecting setuptools Using cached Collecting wheel Using cached Installing collected packages: pip, setuptools, wheel The script wheel is installed in '/home/myusername/.local/bin' which is not on PATH. Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

    The --user switch specifies that you want to install pip in your user's local home directory. This is required if you don't have root/administrator permissions. If you don't specify --user, pip tries to install in a system folder for all users.

  2. Ensure that the pip installation folder is in your PATH environment variable. The installer typically informs you if it's not, as shown in the previous example. To address this, add a statement like the following at the end of your shell's RC script, which is appropriate if pip was installed into the .local/bin folder in your home directory.

    export PATH=~/.local/bin:$PATH
  3. Now you can use pip to install the AWS CLI.

    $ pip install awscli --user

    We again recommend that you use the --user switch to install the AWS CLI in your local home folder, which doesn't require root/administrator permissions.

Step 2: Configure the AWS CLI

First, configure the AWS CLI with your credentials and default settings.

$ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-east-2 Default output format [None]: json

The AWS CLI prompts you for the following information:

  • AWS Access Key ID and AWS Secret Access Key – These are your user or account credentials. If you don't have keys, see Access Keys (Access Key ID and Secret Access Key) in the Amazon Web Services General Reference.

  • Default region name – This specifies the name of the AWS Region you want the CLI to send its requests to by default.

  • Default output format – This specifies the output format you want the CLI to use by default. The value can be json, text, or table. If you don't specify an output format, json is used.

Now try a simple command to verify that your credentials are configured correctly and that you can connect to AWS.

$ aws ec2 describe-regions --output table ---------------------------------------------------------- | DescribeRegions | +--------------------------------------------------------+ || Regions || |+-----------------------------------+------------------+| || Endpoint | RegionName || |+-----------------------------------+------------------+| || | ap-south-1 || || | eu-west-3 || || | eu-west-2 || || | eu-west-1 || || | ap-northeast-3 || || | ap-northeast-2 || || | ap-northeast-1 || || | sa-east-1 || || | ca-central-1 || || | ap-southeast-1 || || | ap-southeast-2 || || | eu-central-1 || || | us-east-1 || || | us-east-2 || || | us-west-1 || || | us-west-2 || |+-----------------------------------+------------------+|

Step 3: Create a Security Group and Key Pair for the Amazon EC2 Instance

In this step, you set up the prerequisites for launching an Amazon EC2 instance that can be accessed with a terminal emulator connected using the Secure Shell (SSH) protocol. For more information about Amazon EC2 and its features, see the Amazon EC2 User Guide for Linux Instances.

Amazon EC2 requires the following prerequisites to communicate with an EC2 instance:

  • Security group – Determines what network traffic is allowed to enter and leave your instance. You can think of a security group as a virtual firewall around the instances that are attached to the group. A security group contains rules that control inbound and outbound network traffic.

  • Key pair – Public–key cryptography uses a public key to encrypt a piece of data, such as a password, then the recipient uses the private key to decrypt the data. Amazon EC2 uses the specified key pair to encrypt the credentials used to access the instance.

To create a security group and key pair

  1. Create a security group for the VPC in which you'll launch the instance. If you're using the default VPC for your account, you can omit the --vpc-id parameter; otherwise, specify the ID of the VPC in which you'll launch your instance. The output shows the identifier of your new security group.

    $ aws ec2 create-security-group --group-name devenv-sg --vpc-id vpc-xxxxxxxx --description "Security group for development environment" { "GroupId": "sg-b018ced5" }
  2. Create a rule for your security group that enables inbound network traffic on port 22 from the CIDR network address range that you'll use to connect to the instance.


    This example shows the CIDR range which enables inbound traffic from anywhere on the internet. We strongly recommend that you replace this with the public CIDR range of the network (as seen by AWS) from which you'll connect to your instance.

    $ aws ec2 authorize-security-group-ingress --group-name devenv-sg --protocol tcp --port 22 --cidr

    Make a note of the security group ID. You'll need it later when you launch the instance.

  3. Create the SSH cryptographic key pair that you'll use to connect to the instance. This example command shows how to save the contents of the key to a file named devenv-key.pem.

    $ aws ec2 create-key-pair --key-name devenv-key --query "KeyMaterial" --output text > devenv-key.pem

    The --query "KeyMaterial" parameter extracts only the part of the output that you need in the .pem file.

    Double quotation marks for the --query parameter

    All of the examples in this topic that include the --query parameter use double quotation marks . Although Linux lets you use single quotation marks for the --query parameter, the Windows command prompt requires you to use double quotation marks instead of single quotation marks.

  4. On Linux, change the access for the new key file so that only you have access to it.

    $ chmod 400 devenv-key.pem

Step 4: Launch and Connect to the Instance

You are now ready to launch an instance and connect to it.

To launch and connect to the instance

  1. Run the following command, using the ID of the security group that you created in the previous step. The --image-id parameter specifies the Amazon Machine Image (AMI) that Amazon EC2 uses to bootstrap the instance. You can find an image ID for your AWS Region and operating system using the Amazon EC2 console. If you're are using the default subnet for a default VPC, you can omit the --subnet-id parameter; otherwise, specify the ID of the subnet in which you'll launch your instance.


    This example shows the command split across multiple lines with the Linux '\' line continuation character. You can, of course, submit it all as a single line. For the Windows command line, replace the '\' with a '^'.

    $ aws ec2 run-instances --image-id ami-xxxxxxxx \ --subnet-id subnet-xxxxxxxx \ --security-group-ids sg-b018ced5 \ --count 1 \ --instance-type t2.micro \ --key-name devenv-key \ --query "Instances[0].InstanceId" "i-0787e4282810ef9cf"
  2. The instance takes a few moments to launch. After the instance is up and running, you can retrieve the public IP address of the instance that you'll need to connect to it by using the following command.

    $ aws ec2 describe-instances --instance-ids i-0787e4282810ef9cf --query "Reservations[0].Instances[0].PublicIpAddress" ""
  3. To connect to the instance, use the public IP address and private key .pem file with your preferred terminal program. On Linux, macOS, or Unix, you can do this from the command line using the following command.

    $ ssh -i devenv-key.pem user@

    If you get an error like Permission denied (publickey) when attempting to connect to your instance, check that the following are correct:

    • Key – The key specified must be at the path indicated and must be the private key, not the public one. Permissions on the key must be restricted to the owner.

    • User – The user name must match the default user name associated with the AMI you used to launch the instance. For an Ubuntu AMI, this is ubuntu. For an Amazon Linux AMI, it's ec2-user.

    • Instance – The public IP address or DNS name of the instance. Verify that the address is public and that port 22 is open to your local machine on the instance's security group.

    You can also use the -v option to view additional information related to the error.

    SSH on Windows

    On Windows, you can use the PuTTY terminal application available here. Get putty.exe and puttygen.exe from the downloads page.

    Use puttygen.exe to convert your private key to a .ppk file required by PuTTY. Launch putty.exe, enter the public IP address of the instance in the Host Name field, and set the connection type to SSH.

    In the Category panel, navigate to Connection, SSH, Auth, and then choose Browse to select your .ppk file. Then choose Open to connect.

  4. The terminal prompts you to accept the server's public key. Type yes and press Enter to complete the connection.

You've now configured a security group, created a key pair, launched an EC2 instance, and connected to it without ever leaving the command line.