Tutorial: Getting started with AWS CloudShell - AWS CloudShell

Tutorial: Getting started with AWS CloudShell

This introductory tutorial shows you how to launch AWS CloudShell and perform key tasks using the shell command line interface.

First, you'll sign in to the AWS Management Console and launch AWS CloudShell in a new browser window. You'll then select an AWS Region and a shell type to work with.

Next, you'll create a new folder in your home directory and upload a file to it from your local machine. You'll work on that file using a pre-installed editor before running it as a program from the command line. Finally, you'll call AWS CLI commands to create an Amazon S3 bucket and add your file as an object to it.


IAM permissions

The quickest way to obtain permissions for AWS CloudShell is to attach the following AWS managed policy to your IAM identity (user, role, or group):

  • AWSCloudShellFullAccess: Provides users with full access to AWS CloudShell and its features.

For this tutorial, you also interact with AWS services (in this case, creating an Amazon S3 bucket and adding an object to it.) So your IAM identity requires a policy that grants, at a minimum, the s3:CreateBucket and s3:PutObject permissions.

For more information, see Amazon S3 Actions in the Amazon Simple Storage Service Developer Guide.

Exercise file

This exercise also involves uploading and editing a file that's then run as a program from the command line interface. Open a text editor on your local machine and add the following code snippet:

import sys x=int(sys.argv[1]) y=int(sys.argv[2]) sum=x+y print("The sum is",sum)

Save the file with the name add_prog.py.


Step 1: Sign in to AWS Management Console

This step involves entering your IAM user information to access the AWS Management Console. If you're already in the console, skip to step 2.

  • You can access the AWS Management Console by using an IAM users sign-in URL or going to the main sign-in page.

    IAM user sign-in URL
    • Open a browser and enter the following sign-in URL, replacing account_alias_or_id with the account alias or account ID provided by your administrator:

    • Enter your IAM user name and password and choose Sign in.

                              Signing in as an IAM user
    Main sign-in page
    • Open https://aws.amazon.com/console/.

    • If you haven't signed in previously using this browser, the main sign-in page appears. Choose IAM user, enter the account alias or account ID, and choose Next.

                                    Signing in as an IAM user
    • If you already signed in as an IAM user before. Your browser might remember the account alias or account ID for the AWS account. If so, enter your IAM user name and password and choose Sign in.

                                    Signing in as an IAM user

    You also have the option of signing in as a root user. This identity has complete access to all AWS services and resources in the account. We strongly recommend that you don't use the root user for everyday tasks, even administrative ones. Instead, adhere to the best practice of using the root user only to create your first IAM user.

Step 2: Launch AWS CloudShell, select a Region, and choose a shell.

In this step, you launch AWS CloudShell from the console interface, choose an available AWS Region, and switch to your preferred shell (Bash, PowerShell, or Z shell).

  1. From the AWS Management Console, you can launch AWS CloudShell by choosing the following options available on the navigation bar:

    • Choose the AWS CloudShell icon.

    • Start typing "cloudshell" in Search box and then choose the CloudShell option.

                  Key features in the AWS CloudShell interface.

    When AWS CloudShell launches in a new browser window for the first time, a welcome panel displays and lists key features. After you close this panel, status updates are provided while the shell configures and forwards your console credentials. When the command prompt displays, the shell is ready for interaction.


    If you encounter issues that prevent you from successfully launching or interacting with AWS CloudShell, check for information to identify and address those issues in Troubleshooting AWS CloudShell.

  2. To choose an AWS Region to work in, go to the Select a Region menu and select a supported AWS Region to work in. (Available Regions are highlighted.)


    If you switch Regions, the interface refreshes and the name of the selected AWS Region is displayed above the command line text. Any files that you add to persistent storage are available only in this same AWS Region. If you change Regions, different storage (and files) are accessible.

  3. To choose a pre-installed shell to work with, enter its program name at the command line prompt:



    If you switch to Bash, the symbol at the command prompt updates to $.


    Bash is the default shell that's running when you launch AWS CloudShell.



    If you switch to PowerShell, the symbol at the command prompt updates to PS>.

    Z shell


    If you switch to Z shell, the symbol at the command prompt updates to %.

Step 3: Upload a file to AWS CloudShell

This step walks you through the process of uploading a file and then moving it to a new directory in your home directory.

  1. To check your current working directory, at the prompt enter the following command:


    When you press Enter, the shell returns your current working directory. For example: /home/cloudshell-user.

  2. To upload a file to this directory, go to Actions and select Upload file from the menu.

                     Key features in the AWS CloudShell interface.

    The Upload file dialog box displays.

  3. Choose Browse.

  4. In your system's File upload dialog box, select the text file you created for this tutorial (add_prog.py) and choose Open.

  5. In the Upload file dialog box, choose Upload.

    A progress bar tracks the upload. If the upload is successful, a message confirms that add_prog.py was added to the root of your home directory.

  6. To create a directory for the file, enter the make directories command: mkdir mysub_dir.

  7. To move the uploaded file from the root of your home directory to the new directory, use the mv command:

    mv add_prog.py mysub_dir.

  8. To change your working directory to the new directory, enter cd mysub_dir.

    The command prompt updates to indicate you've changed your working directory.

  9. To view the contents of the current directory, mysub_dir, enter the ls command.

    The contents of the working directory, including the file you just uploaded, are listed.

Step 4: Edit your file's code and run it from the command line

This step demonstrates how to use the pre-installed Vim editor to work with a file. You then run that file as a program from the command line.

  1. To edit the file you uploaded in the previous step, enter the following command:

    vim add_prog.py

    The shell interface refreshes to display the Vim editor.

  2. To edit the file in Vim, press the I key. Now edit the contents so the program adds up three numbers instead of two:

    import sys x=int(sys.argv[1]) y=int(sys.argv[2]) z=int(sys.argv[3]) sum=x+y+z print("The sum is",sum)

    If you paste the text into the editor and have the Safe Paste feature enabled, a warning is displayed. Multiline text that's copied can contain malicious scripts. With Safe Paste, you can verify the complete text before it's pasted in. If you're satisfied that the text is safe, choose Paste.

  3. After you edited the program, press Esc to enter the Vim command mode. Then, enter the following command to save the file and exit the editor:



    If you're new to Vim, you might initially find it challenging to switch between command mode (used when saving files and exiting the application) and insert mode (used when inserting new text). As a friendly point of reference, to enter insert mode, press I, and, to enter command mode, press Esc. For more information about Vim and other tools available in AWS CloudShell, see Development tools and shell utilities.

  4. Back in the main command line interface, run the program and specify three numbers for input:

    python3 add_prog.py 4 5 6

    The command line displays the program output: The sum is 15.

Step 5: Use AWS CLI to add the file as an object in an Amazon S3 bucket.

In this step, you create an Amazon S3 bucket and then use the PutObject method to add your code file as an object in that bucket.


In most cases, you can use a service such as CodeCommit to commit a software file into a version-controlled repository. This introductory tutorial uses Amazon S3 for storage to show how easy it is to use AWS CLI in AWS CloudShell. Using this method, you don't need to download or install any additional resource. Moreover, because you're already authenticated within the shell, you don't need to configure credentials before making calls.

  1. To create a bucket in a specified AWS Region, enter the following command:

    aws s3api create-bucket --bucket insert-unique-bucket-name-here --region us-east-1

    If the call is successful, the command line displays a response from the service similar to the following output:

    { "Location": "/insert-unique-bucket-name-here" }

    If you don't adhere to the rules for naming buckets (using only lowercase letters, for example), the following error is displayed: An error occurred (InvalidBucketName) when calling the CreateBucket operation: The specified bucket is not valid.

  2. To upload a file and add it as an object to the bucket that was just created, call the PutObject method:

    aws s3api put-object --bucket insert-unique-bucket-name-here --key add_prog --body add_prog.py

    If the object is successfully uploaded to the Amazon S3 bucket, the command line displays a response from the service similar to the following output:

    { "ETag": "\"ab123c1:w:wad4a567d8bfd9a1234ebeea56\"" }

    The ETag is the hash of the object that's been stored. It can be used to check the integrity of the object uploaded to Amazon S3.