Working with AWS CloudShell - AWS CloudShell
Launching AWS CloudShellNavigating the AWS CloudShell interfaceChoosing shellsWorking in AWS RegionsWorking with files and storageStarting and ending shell sessions

Working with AWS CloudShell

This topic describes how you can access AWS CloudShell, navigate the shell interface, choose a shell type, work with file uploads and downloads, and manage your shell sessions.

Launching AWS CloudShell

You can launch AWS CloudShell from the AWS Management Console using either one of the following two methods:

  1. Choose the AWS CloudShell icon on the console navigation bar.

  2. Start typing "cloudshell" in the Find Services box and then choose the CloudShell option.

Key features in the AWS CloudShell interface.

The following screenshot indicates several key AWS CloudShell interface features. You use these features when you use the command line, use file upload/download tools, customize your shell environment, and access user assistance.

Key features of the AWS CloudShell interface.

  1. AWS CloudShell command line interface that you use to run commands using your preferred shell. The current shell type is indicated by the command prompt.

  2. The AWS Region where AWS CloudShell is currently running.

  3. The Notification link, which provides access to your Personal Health Dashboard and event logs.

  4. The name and account ID of the current AWS CloudShell user (blurred here). You can use this menu to view account information, switch roles, and sign out of AWS.

  5. The Region selector that allows you to choose which AWS Region your shell environment runs in. For more information, see Supported AWS Regions for AWS CloudShell.

  6. The Support menu, which you use to access user-assistance resources, including documentation and training.

  7. The Actions menu, which provides options for changing the screen layout, downloading and uploading files, and restarting your AWS CloudShell.

  8. The Preferences option, which you can use to customize your shell experience. You do this by changing text size and switching the interface's color theme.

  9. The bottom bar, which has options to provide feedback, access localized versions of the interface, and learn about our privacy policy and terms of use.

Choosing your shell

The following shells are pre-installed and ready for use in AWS CloudShell: the Bash shell, PowerShell, and the Z shell. For information about the versions pre-installed in your shell environment, see the shells table in the AWS CloudShell compute environment section.

You can identify the shell that you're currently in by the command prompt:

  • $: Bash shell

  • PS>: PowerShell

  • %: Z shell

To switch to a new shell, enter the shell's program name at the command line prompt:

  • bash: Bash

  • pwsh: PowerShell

  • zsh: Z shell

Working in AWS Regions

The current AWS Region that you're running in is displayed above the command line interface.

Key features of the AWS CloudShell interface.

You can choose an AWS Region to work in by selecting one from the Region selector. After you change Regions, the interface refreshes as your shell session connects to a compute environment that's running in the selected Region.

Important

You have persistent storage of 1 GB for each AWS Region. The persistent storage is located in your home directory ($HOME). Therefore, the personal files, directories, programs, and scripts that are stored in your home directory in one AWS Region. Moreover, they are different from those that are located in the home directory and stored a different Region.

Long-term retention of files in persistent storage is also managed on a per-Region basis. For more information, see Persistent storage.

Specifying your default AWS Region for AWS CLI

You can use environment variables to specify configuration options and credentials required to access AWS services using AWS CLI. The environment variable that specifies the default AWS Region for your shell session is set when you launch AWS CloudShell from a specific Region in the AWS Management Console or when you choose an option in the Region selector.

Because environment variables have precedence over AWS CLI credentials files that are updated by aws configure, you can't run that command to change the Region that's specified by the environment variable. To change the default Region for AWS CLI commands, assign a value to the AWS_REGION environment variable. In the examples below, you can replace us-east-1 with your choice of Region.

Bash or Zsh
$ export AWS_REGION=us-east-1

Setting the environment variable changes the value used until the end of your shell session, or until you set the variable to a different value. You can make the variables persistent across future sessions by setting them in your shell's startup script.

PowerShell
PS C:\> $Env:AWS_REGION="us-east-1"

If you set an environment variable at the PowerShell prompt, it saves the value for only the duration of the current session. Alternatively, you can set the variable for all future PowerShell sessions by adding it to your PowerShell profile. See the PowerShell documentation for more information about storing environment variables or persisting them across sessions.

To confirm that you've changed the default Region, you can display the current AWS CLI configuration data by running the following command:

aws configure list
Note

For specific AWS CLI commands, you can override the default Region using the command line option --region. For more information, see Command line options in the AWS Command Line Interface User Guide.

Working with files and storage

Using AWS CloudShell's interface, you can upload files to and download files from the shell environment. To ensure any of the files you add are available after your session ends, you should know the difference between persistent and temporary storage:

  • Persistent storage: You have 1 GB of persistent storage for each AWS Region. Persistent storage is located on your home directory.

  • Temporary storage: Temporary storage exists in directories outside your home directory and is recycled at the end of a session.

Important

Files you want to keep and use for future shell sessions should always be left in your home directory. If you move a file out of your home directory (using the mv command, for example), it's recycled when the current shell session ends.

To download files from AWS CloudShell

  1. Choose Actions, Download file.

  2. In the Download file dialog box, enter the path for the file to be downloaded.

    Specifying a path for a file download.
    Note

    You can use absolute or relative paths when specifying a file for download. With relative pathnames, /home/cloudshell-user/ is added automatically to the start by default. So to download a file called mydownload-file, both of the following are valid paths:

    • Absolute path: /home/cloudshell-user/subfolder/mydownloadfile.txt

    • Relative path: subfolder/mydownloadfile.txt

  3. Choose Download.

    If the file path is correct, a dialog box displays. You can use this dialog box to open the file with the default application. Or you can save the file to a folder on your local machine.

To upload files to AWS CloudShell

  1. Choose Actions, Upload file.

    Note

    By default, files are uploaded to the root of your home directory: /home/cloudshell-user. If you move files (with the mv command, for example), ensure that the files stay in your home directory. This is where your 1 GB of persistent storage is located.

  2. In the Upload file dialog box, choose Browse to select a file on your local machine. (The maximum upload size is 1 GB.)

  3. In your system Upload file dialog box, select a file to upload and choose Open.

  4. Choose Upload to add the selected file to the shell environment.

    Uploading a selected file.

    If you try to upload a file that causes you to exceed your per-Region limit, you're notified that the upload can't continue. For example, you're told that the upload can't complete if you try to upload a 200MB file when you've already stored 900MB of data in your home directory.

To remove files from AWS CloudShell

  1. To remove files from AWS CloudShell, use standard shell commands such as rm (remove):

    rm my-file-for-removal

  2. You can also remove multiple files that meet specified criteria using the find command. The following example removes all files that feature the phrase ".pdf" in their names:

    find -type f -name '*pdf*' -delete
Note

If you stop using AWS CloudShell in an AWS Region, data in that Region's persistent storage is removed automatically after a defined period. For more information, see Persistent storage.

Starting and ending shell sessions

Note

As a security measure, if you don't interact with the shell using the keyboard or pointer for an extended period, the session stops automatically. Very long-running sessions are also automatically stopped. For more information, see Shell sessions.

Restarting shell sessions

  1. You can restart a shell session by choosing Actions, Restart CloudShell.

    You're notified that restarting AWS CloudShell stops all active sessions in the current AWS Region.

  2. Choose Restart to confirm.

    An interface displays a message that the AWS CloudShell compute environment is stopping. After the environment has stopped and restarted, you can start working with the command line in a new session.

Note

In some cases, it may take a few minutes for your environment to restart.

Manually exiting shell sessions

With the command line, you can leave a shell session and log out using the exit command. You can then press any key to reconnect and continue to use AWS CloudShell.