# Setting up the EB command line interface (EB CLI) to manage Elastic Beanstalk
<a name="eb-cli3"></a>

The EB CLI is a command line interface which provides interactive commands to create, update, and monitor environments in AWS Elastic Beanstalk. The EB CLI open-source project is on Github: `[aws/aws-elastic-beanstalk-cli](https://github.com/aws/aws-elastic-beanstalk-cli)`

After you install the EB CLI and configure a project directory, you can create environments with a single command:

```
$ eb create my-beanstalk-environment
```

We recommend installing with the setup script, learn how in [Install EB CLI with setup script (recommended)](#eb-cli3-install).

 The AWS CLI provides direct access to low-level Elastic Beanstalk APIs. Although powerful, it is also verbose and less preferred over the EB CLI. For example, creating an environment with the AWS CLI requires the following series of commands:

```
$ aws elasticbeanstalk check-dns-availability \
    --cname-prefix my-cname
$ aws elasticbeanstalk create-application-version \
    --application-name my-application \
    --version-label v1 \
    --source-bundle S3Bucket=amzn-s3-demo-bucket,S3Key=php-proxy-sample.zip
$ aws elasticbeanstalk create-environment \
    --cname-prefix my-cname \
    --application-name my-app \
    --version-label v1 \
    --environment-name my-env \
    --solution-stack-name "64bit Amazon Linux 2023 v4.5.0 running Ruby 3.4"
```

## Install EB CLI with setup script (recommended)
<a name="eb-cli3-install"></a>

**We recommend the installer script**  
We recommend using the installer script to set up the EB CLI and its dependencies and prevent potential conflicts with other Python packages.

Pre-requisites: Git, Python, and [virtualenv](https://virtualenv.pypa.io/en/latest/installation.html)

**To download and use the installer script**

1. Clone the repository.

   ```
   git clone https://github.com/aws/aws-elastic-beanstalk-cli-setup.git
   ```

1. Install or upgrade the EB CLI.

   **macOS / Linux** in Bash or Zsh

   ```
   python ./aws-elastic-beanstalk-cli-setup/scripts/ebcli_installer.py
   ```

   **Windows** in PowerShell or Command window

   ```
   python .\aws-elastic-beanstalk-cli-setup\scripts\ebcli_installer.py
   ```

1. Verify that the EB CLI is installed correctly.

   ```
   $ eb --version
   EB CLI 3.21.0 (Python 3.12)
   ```

For complete installation instructions, see the [https://github.com/aws/aws-elastic-beanstalk-cli-setup](https://github.com/aws/aws-elastic-beanstalk-cli-setup) repository on GitHub.

## Manually install the EB CLI
<a name="eb-cli3-install-advanced"></a>

You can install the EB CLI on Linux, macOS, and Windows with the `pip` package manager for Python which provides installation, upgrade, and removal of Python packages and their dependencies. 

**We recommend the installer script**  
We recommend using the [Install EB CLI](#eb-cli3-install) to set up the EB CLI and prevent dependency conflicts.

**Prerequisite** - You must have a supported version of Python installed. You can download it from the [Python downloads](https://www.python.org/downloads/) page on the Python website.

**To install the EB CLI (manually)**

1. Run the following command.

   ```
   $ pip install awsebcli --upgrade --user
   ```

   The `--upgrade` option tells `pip` to upgrade any requirements that are already installed. The `--user` option tells `pip` to install the program to a subdirectory of your user directory to avoid modifying libraries that your operating system uses.
**Troubleshooting issues**  
If you encounter issues when you try to install the EB CLI with `pip`, you can [install the EB CLI in a virtual environment](#eb-cli3-install-virtualenv) to isolate the tool and its dependencies, or use a different version of Python than you normally do.

1. Add the path to the executable file to your `PATH` variable:
   + On Linux and macOS:

     **Linux** – `~/.local/bin`

     **macOS** – `~/Library/Python/3.12/bin`

     To modify your `PATH` variable (Linux, Unix, or macOS ):

     1. Find your shell's profile script in your user folder. If you are not sure which shell you have, run `echo $SHELL`.

        ```
        $ ls -a ~
        .  ..  .bash_logout  .bash_profile  .bashrc  Desktop  Documents  Downloads
        ```
        + **Bash** – `.bash_profile`, `.profile`, or `.bash_login`.
        + **Zsh** – `.zshrc`
        + **Tcsh** – `.tcshrc`, `.cshrc` or `.login`.

     1. Add an export command to your profile script. The following example adds the path represented by *LOCAL\$1PATH* to the current `PATH` variable.

        ```
        export PATH=LOCAL_PATH:$PATH
        ```

     1. Load the profile script described in the first step into your current session. The following example loads the profile script represented by *PROFILE\$1SCRIPT*. 

        ```
        $ source ~/PROFILE_SCRIPT
        ```
   + On Windows:

     **Python 3.12** – `%USERPROFILE%\AppData\Roaming\Python\Python312\Scripts`

     **Python earlier versions** – `%USERPROFILE%\AppData\Roaming\Python\Scripts`

     To modify your `PATH` variable (Windows):

     1. Press the Windows key, and then enter **environment variables**.

     1. Choose **Edit environment variables for your account**.

     1. Choose **PATH**, and then choose **Edit**.

     1. Add paths to the **Variable value** field, separated by semicolons. For example: `C:\item1\path;C:\item2\path`

     1. Choose **OK** twice to apply the new settings.

     1. Close any running Command Prompt windows, and then reopen a Command Prompt window.

1. Verify that the EB CLI installed correctly by running **eb --version**.

   ```
   $ eb --version
   EB CLI 3.21.0 (Python 3.12)
   ```

The EB CLI is updated regularly to add functionality that supports [the latest Elastic Beanstalk features](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/). To update to the latest version of the EB CLI, run the installation command again.

```
$ pip install awsebcli --upgrade --user
```

If you need to uninstall the EB CLI, use `pip uninstall`.

```
$ pip uninstall awsebcli
```

## Install the EB CLI in a virtual environment
<a name="eb-cli3-install-virtualenv"></a>

You can avoid version requirement conflicts with other `pip` packages by installing the EB CLI in a virtual environment.

**To install the EB CLI in a virtual environment**

1. First, install `virtualenv` with `pip`.

   ```
   $ pip install --user virtualenv
   ```

1. Create a virtual environment.

   ```
   $ virtualenv ~/eb-ve
   ```

   To use a Python executable other than the default, use the `-p` option. 

   ```
   $ virtualenv -p /usr/bin/python3.12 ~/eb-ve
   ```

1. Activate the virtual environment.

   **Linux, Unix, or macOS**

   ```
   $ source ~/eb-ve/bin/activate
   ```

   **Windows**

   ```
   $ %USERPROFILE%\eb-ve\Scripts\activate
   ```

1. Install the EB CLI.

   ```
   (eb-ve)$ pip install awsebcli --upgrade
   ```

1. Verify that the EB CLI is installed correctly.

   ```
   $ eb --version
   EB CLI 3.23.0 (Python 3.12)
   ```

You can use the `deactivate` command to exit the virtual environment. Whenever you start a new session, run the activation command again.

To upgrade to the latest version, run the installation command again.

```
(eb-ve)$ pip install awsebcli --upgrade
```

## Install the EB CLI with homebrew
<a name="eb-cli3-install-osx-homebrew"></a>

The latest version of the EB CLI is typically available from `Homebrew` a couple of days after it appears in `pip`.

**We recommend the installer script**  
We recommend using the [Install EB CLI](#eb-cli3-install) to set up the EB CLI and prevent dependency conflicts.

**To install the EB CLI with `Homebrew`**

1. Ensure you have the latest version of `Homebrew`.

   ```
   $ brew update
   ```

1. Run `brew install awsebcli`.

   ```
   $ brew install awsebcli
   ```

1. Verify that the EB CLI is installed correctly.

   ```
   $ eb --version
   EB CLI 3.21.0 (Python 3.12)
   ```

# Configure the EB CLI
<a name="eb-cli3-configuration"></a>

After [installing the EB CLI](eb-cli3.md#eb-cli3-install), you are ready to configure your project directory and the EB CLI by running **eb init**.The following example shows the configuration steps when running **eb init** for the first time in a project folder named `eb`.

**To initialize an EB CLI project**

1. First, the EB CLI prompts you to select a region. Choose your preferred region.

   ```
   ~/eb $ eb init
   Select a default region
   1) us-east-1 : US East (N. Virginia)
   2) us-west-1 : US West (N. California)
   3) us-west-2 : US West (Oregon)
   4) eu-west-1 : Europe (Ireland)
   5) eu-central-1 : Europe (Frankfurt)
   6) ap-south-1 : Asia Pacific (Mumbai)
   7) ap-southeast-1 : Asia Pacific (Singapore)
   ...
   (default is 3): 3
   ```

1. If prompted, provide your access key and secret key so that the EB CLI can manage resources for you. Access keys are created in the AWS Identity and Access Management console. If you don't have keys, see [How Do I Get Security Credentials?](https://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html) in the *Amazon Web Services General Reference*.

   ```
   You have not yet set up your credentials or your credentials are incorrect.
   You must provide your credentials.
   (aws-access-id): AKIAJOUAASEXAMPLE
   (aws-secret-key): 5ZRIrtTM4ciIAvd4EXAMPLEDtm+PiPSzpoK
   ```

1. An Elastic Beanstalk application is a resource that contains a set of application versions (source), environments, and saved configurations that are associated with a single web application. Each time you deploy your source code to Elastic Beanstalk using the EB CLI, a new application version is created and added to the list.

   ```
   Select an application to use
   1) [ Create new Application ]
   (default is 1): 1
   ```

1. The default application name is the name of the folder in which you run **eb init**. Enter any name that describes your project.

   ```
   Enter Application Name
   (default is "eb"): eb
   Application eb has been created.
   ```

1. Select a platform that matches the language or framework that your web application is developed in. If you haven't started developing an application yet, choose a platform that you're interested in. You will see how to launch a sample application shortly, and you can always change this setting later.

   ```
   Select a platform.
   1) .NET Core on Linux
   2) .NET on Windows Server
   3) Docker
   4) Go
   5) Java
   6) Node.js
   7) PHP         <== select platform by number
   8) Packer
   9) Python
   10) Ruby
   11) Tomcat
   (make a selection):7
   ```

1. Select a specific platform branch.

   ```
   Select a platform branch.
   1) PHP 8.4 running on 64bit Amazon Linux 2023
   2) PHP 8.3 running on 64bit Amazon Linux 2023
   3) PHP 8.2 running on 64bit Amazon Linux 2023
   4) PHP 8.1 running on 64bit Amazon Linux 2023
   5) PHP 8.1 running on 64bit Amazon Linux 2
   (default is 1):1
   ```

1. Choose **yes** to assign an SSH key pair to the instances in your Elastic Beanstalk environment. This allows you to connect directly to them for troubleshooting.

   ```
   Do you want to set up SSH for your instances?
   (y/n): y
   ```

1. Choose an existing key pair or create a new one. To use **eb init** to create a new key pair, you must have **ssh-keygen** installed on your local machine and available from the command line. The EB CLI registers the new key pair with Amazon EC2 for you and stores the private key locally in a folder named `.ssh` in your user directory.

   ```
   Select a keypair.
   1) [ Create new KeyPair ]
   (default is 1): 1
   ```

Your EB CLI installation is now configured and ready to use.

**Topics**
+ [Ignoring files using .ebignore](#eb-cli3-ebignore)
+ [Using named profiles](#eb-cli3-profile)
+ [Deploying an artifact instead of the project folder](#eb-cli3-artifact)
+ [Configuration settings and precedence](#eb-cli3-credentials)
+ [Instance metadata](#eb-cli3-metadata)

## Ignoring files using .ebignore
<a name="eb-cli3-ebignore"></a>

You can tell the EB CLI to ignore certain files in your project directory by adding the file `.ebignore` to the directory. This file works like a `.gitignore` file. When you deploy your project directory to Elastic Beanstalk and create a new application version, the EB CLI doesn't include files specified by `.ebignore` in the source bundle that it creates.

If `.ebignore` isn't present, but `.gitignore` is, the EB CLI ignores files specified in `.gitignore`. If `.ebignore` is present, the EB CLI doesn't read `.gitignore`.

When `.ebignore` is present, the EB CLI doesn't use git commands to create your source bundle. This means that EB CLI ignores files specified in `.ebignore`, and includes all other files. In particular, it includes uncommitted source files.

**Note**  
In Windows, adding `.ebignore` causes the EB CLI to follow symbolic links and include the linked file when creating a source bundle. This is a known issue and will be fixed in a future update.

## Using named profiles
<a name="eb-cli3-profile"></a>

If you store your credentials as a named profile in a `credentials` or `config` file, you can use the [`--profile`](eb3-cmd-options.md) option to explicitly specify a profile. For example, the following command creates a new application using the `user2` profile.

```
$ eb init --profile user2
```

You can also change the default profile by setting the `AWS_EB_PROFILE` environment variable. When this variable is set, the EB CLI reads credentials from the specified profile instead of `default` or **eb-cli**.

**Linux, macOS, or Unix**

```
$ export AWS_EB_PROFILE=user2
```

**Windows**

```
> set AWS_EB_PROFILE=user2
```

## Deploying an artifact instead of the project folder
<a name="eb-cli3-artifact"></a>

You can tell the EB CLI to deploy a ZIP file or WAR file that you generate as part of a separate build process by adding the following lines to `.elasticbeanstalk/config.yml` in your project folder.

```
deploy:
  artifact: path/to/buildartifact.zip
```

If you configure the EB CLI in your [Git repository](eb3-cli-git.md), and you don't commit the artifact to source, use the `--staged` option to deploy the latest build.

```
~/eb$ eb deploy --staged
```

## Configuration settings and precedence
<a name="eb-cli3-credentials"></a>

The EB CLI uses a *provider chain* to look for AWS credentials in a number of different places, including system or user environment variables and local AWS configuration files.

The EB CLI looks for credentials and configuration settings in the following order:

1. **Command line options** – Specify a named profile by using `--profile` to override default settings.

1. **Environment variables** – `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.

1. **The AWS credentials file** – Located at `~/.aws/credentials` on Linux and OS X systems, or at `C:\Users\USERNAME\.aws\credentials` on Windows systems. This file can contain multiple named profiles in addition to a default profile.

1. **The [AWS CLI configuration file](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)** – Located at `~/.aws/config` on Linux and OS X systems or `C:\Users\USERNAME\.aws\config` on Windows systems. This file can contain a default profile, [named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-multiple-profiles), and AWS CLI–specific configuration parameters for each.

1. **Legacy EB CLI configuration file** – Located at `~/.elasticbeanstalk/config` on Linux and OS X systems or `C:\Users\USERNAME\.elasticbeanstalk\config` on Windows systems.

1. **Instance profile credentials** – These credentials can be used on Amazon EC2 instances with an assigned instance role, and are delivered through the Amazon EC2 metadata service. The [instance profile](concepts-roles-instance.md) must have permission to use Elastic Beanstalk.

If the credentials file contains a named profile with the name "eb-cli", the EB CLI will prefer that profile over the default profile. If no profiles are found, or a profile is found but does not have permission to use Elastic Beanstalk, the EB CLI prompts you to enter keys.

## Instance metadata
<a name="eb-cli3-metadata"></a>

To use the EB CLI from an Amazon EC2 instance, create a role that has access to the resources needed and assign that role to the instance when it is launched. Launch the instance and install the EB CLI by using `pip`.

```
~$ sudo pip install awsebcli
```

`pip` comes preinstalled on Amazon Linux.

The EB CLI reads credentials from the instance metadata. For more information, see [ Granting Applications that Run on Amazon EC2 Instances Access to AWS Resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/role-usecase-ec2app.html) in *IAM User Guide*.

# Using the EB CLI with Git
<a name="eb3-cli-git"></a>

The EB CLI provides a Git integration so you can associate code branches with specific environments in Elastic Beanstalk to organize your deploys.

**To install Git and initialize your Git repository**

1. Download the most recent version of Git by visiting [http://git-scm.com](http://git-scm.com).

1. Initialize your Git repository by typing the following:

   ```
   ~/eb$ git init
   ```

   EB CLI will now recognize that your application is set up with Git.

1. If you haven't already run **eb init**, do that now: 

   ```
   ~/eb$ eb init
   ```

## Associating Elastic Beanstalk environments with Git branches
<a name="eb3-cli-git.branches"></a>

You can associate a different environment with each branch of your code. When you checkout a branch, changes are deployed to the associated environment. For example, you can type the following to associate your production environment with your mainline branch, and a separate development environment with your development branch:

```
~/eb$ git checkout mainline
~/eb$ eb use prod
~/eb$ git checkout develop
~/eb$ eb use dev
```

## Deploying changes
<a name="eb3-cli-git.deploy"></a>

By default, the EB CLI deploys the latest commit in the current branch, using the commit ID and message as the application version label and description, respectively. If you want to deploy to your environment without committing, you can use the `--staged` option to deploy changes that have been added to the staging area.

**To deploy changes without committing**

1. Add new and changed files to the staging area:

   ```
   ~/eb$ git add .
   ```

1. Deploy the staged changes with **eb deploy**:

   ```
   ~/eb$ eb deploy --staged
   ```

If you have configured the EB CLI to [deploy an artifact](eb-cli3-configuration.md#eb-cli3-artifact), and you don't commit the artifact to your git repository, use the `--staged` option to deploy the latest build.

## Using Git submodules
<a name="eb3-cli-git.submodules"></a>

Some code projects benefit from having Git submodules — repositories within the top-level repository. When you deploy your code using **eb create** or **eb deploy**, the EB CLI can include submodules in the application version zip file and upload them with the rest of the code.

You can control the inclusion of submodules by using the `include_git_submodules` option in the `global` section of the EB CLI configuration file, `.elasticbeanstalk/config.yml` in your project folder.

To include submodules, set this option to `true`:

```
global:
  include_git_submodules: true
```

When the `include_git_submodules` option is missing or set to `false`, EB CLI does not include submodules in the uploaded zip file.

See [Git Tools - Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more details about Git submodules.

**Default behavior**  
When you run **eb init** to configure your project, the EB CLI adds the `include_git_submodules` option and sets it to `true`. This ensures that any submodules you have in your project are included in your deployments.  
The EB CLI did not always support including submodules. To avoid an accidental and undesirable change to projects that had existed before we added submodule support, the EB CLI does not include submodules when the `include_git_submodules` option is missing. If you have one of these existing projects and you want to include submodules in your deployments, add the option and set it to `true` as explained in this section.

**CodeCommit behavior**  
Elastic Beanstalk's integration with CodeCommit doesn't support submodules at this time. If you enabled your environment to integrate with CodeCommit, submodules are not included in your deployments.

## Assigning Git tags to your application version
<a name="eb3-cli-git.tags"></a>

You can use a Git tag as your version label to identify what application version is running in your environment. For example, type the following:

```
~/eb$ git tag -a v1.0 -m "My version 1.0"
```