Installing Amazon Q for command line - Amazon Q Developer
macOSWindows Subsystem for Linux (WSL)ZIP setup for autocomplete supportUbuntu/Debian (Linux)AppImage (Linux)Alternative Linux builds (musl libc/compatibility build)Handling glibc version issues

Installing Amazon Q for command line

You can install Amazon Q for command line for macOS by initiating a file download for the Amazon Q application. For more information, see Supported command line environments for autocomplete.

There are two modalities to consider when installing Amazon Q for command line. Minimal installation only distributes the binaries needed on Linux for Amazon Q chat and for the autocomplete feature to function over SSH (q and qterm). Full distribution contains the desktop application and requires the autocomplete feature to be used. If you want to only use the Amazon Q chat, consider that the minimal distribution also ships and installs qterm to your shell. You can use qterm for ZShell to support inline completions and a full version isn't required. For more information, see ZIP setup for autocomplete support.

macOS

You can install Amazon Q for command line for macOS by downloading the application or by using Homebrew.

After installing Amazon Q for command line for macOS, you can enable SSH integration to be able to use autocomplete for over 500 command line tools. For more information, see Local macOS Integration.

To install Amazon Q for command line for macOS

  1. Download Amazon Q for command line for macOS.

  2. (Optional) Verify the downloaded file for Amazon Q for command line on macOS. For more information, see Verifying your download.

  3. Authenticate with Builder ID, or with IAM Identity Center using the start URL given to you by your account administrator.

  4. Follow the instructions to install the shell integrations, and to grant macOS accessibility permissions.

To install Amazon Q for command line for macOS with Homebrew

  1. If you don't already have Homebrew installed, install the package manager from brew.sh.

  2. In a working terminal, install Amazon Q for command line using the following command:

    brew install amazon-q

  3. Verify the installation by using the following command:

    q --version

Windows Subsystem for Linux (WSL)

While Amazon Q CLI doesn't have a native Windows version, you can use it on Windows through the Windows Subsystem for Linux (WSL). This provides a Linux environment running on Windows where you can install and use the Amazon Q CLI.

To install Amazon Q for command line for Windows with WSL

  1. Install the WSL on your Windows machine by following the Microsoft WSL installation guide.

  2. Install a Linux distribution such as Ubunu from the Micosoft Store.

  3. Launch your WSL Linux distribution.

  4. Download the appropriate zip file installer version of the Linux package for your WSL distribution. To learn about the different zip files, see ZIP setup for autocomplete support.

    Note

    This is a minimal Linux installation. Desktop Linux users have GUI components available that are not included in the zip installer for remote SSH and Windows WSL systems.

  5. Configure your AWS credentials within the WSL environment using the following command:

    q login
Note

When using Amazon Q CLI in WSL, it has access to files within the WSL filesystem. To work with files on your Windows drives, access them through the /mnt/c/path for C: drive within WSL.

Example

The following procedure steps show how WSL can be installed:

  1. In a working command prompt, install WSL on your windows machine using the following command:

    wsl —install

  2. Run a specific distribution. For Ubuntu, use the following command:

    wsl -d Ubuntu

  3. Create a default account with a password for your newly installed Linux distribution. For more information, see Set up and best practices.

  4. Install the unzip utility for Ubuntu using the following the command:

    sudo apt install unzip

  5. Download the installation file using the following command:

    curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip -o q.zip

  6. Unzip the installation file using the following command:

    unzip q.zip

  7. Execute the install using the following command:

    ./q/install.sh

  8. Address the following:

    1. Do you want q to modify your shell config (you will have to manually do this otherwise)?

    2. Select login method

    3. Enter Start URL

    4. Enter Region

    5. Manually open browser URL.

    6. Complete the login.

  9. Restart the Z Shell to refresh session information and apply changes.

ZIP setup for autocomplete support

The SSH setup for remote Linux integration requires installing the file, verifying the file, and installing the program.

Install and update requirements

  • You must be able to extract or "unzip" the downloaded package. If your operating system doesn't have the built-in unzip command, use an equivalent.

  • Amazon Q for command line uses glibc 2.34 or newer. It's included by default in most major distributions of Linux released since 2021. For older distributions, a version is statically linked with the musl library (-musl.zip).

  • Amazon Q for command line is supported on 64-bit x86_64 and ARM aarch64 versions of recent distributions of Fedora, Ubuntu, and Amazon Linux 2023.

  • AWS doesn't maintain third-party repositories, so it's not a guarantee that they contain the latest version of the Amazon Q command line.

To download the zip file and verify

  1. Download the installation file in one of the following ways:

    Linux x86-64

    curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"

    Linux ARM (aarch64)

    curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" -o "q.zip"

  2. (Optional) Verifying the integrity of your downloaded zip file.

    If you chose to manually download the Amazon Q command line installer package .zip in the above steps, you can use the following steps to verify the signatures by using the GnuPG tool.

    The Amazon Q command line installer package .zip files are cryptographically signed using PGP signatures. If there's any damage or alteration of the files, this verification fails and you should not proceed with installation.

    1. Download and install the gpg command using your package manager. For more information about GnuPG, see the GnuPG documentation.

    2. To create the public key file, create a text file, and then paste in the following text.

      -----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZig60RYJKwYBBAHaRw8BAQdAy/+G05U5/EOA72WlcD4WkYn5SInri8pc4Z6D
BKNNGOm0JEFtYXpvbiBRIENMSSBUZWFtIDxxLWNsaUBhbWF6b24uY29tPoiZBBMW
CgBBFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcFAmYoOtECGwMFCQPCZwAFCwkIBwIC
IgIGFQoJCAsCBBYCAwECHgcCF4AACgkQUNx6jcJMVmef5QD/QWWEGG/cOnbDnp68
SJXuFkwiNwlH2rPw9ZRIQMnfAS0A/0V6ZsGB4kOylBfc7CNfzRFGtovdBBgHqA6P
zQ/PNscGuDgEZig60RIKKwYBBAGXVQEFAQEHQC4qleONMBCq3+wJwbZSr0vbuRba
D1xr4wUPn4Avn4AnAwEIB4h+BBgWCgAmFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcF
AmYoOtECGwwFCQPCZwAACgkQUNx6jcJMVmchMgEA6l3RveCM0YHAGQaSFMkguoAo
vK6FgOkDawgP0NPIP2oA/jIAO4gsAntuQgMOsPunEdDeji2t+AhV02+DQIsXZpoB
=f8yY
-----END PGP PUBLIC KEY BLOCK-----

    3. Import the Amazon Q command line public key with the following command, substituting public-key-file-name with the file name of the public key you created.

      gpg --import public-key-file-name
gpg: directory '/home/username/.gnupg' created
gpg: keybox '/home/username/.gnupg/pubring.kbx' created
gpg: /home/username/.gnupg/trustdb.gpg: trustdb created
gpg: key 50DC7A8DC24C5667: public key "Amazon Q command line Team <q-command line@amazon.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

    4. Download the Amazon Q command line signature file for the package you downloaded. It has the same path and name as the .zip file it corresponds to, but has the extension .sig. In the following examples, we save it to the current directory as a file named q.zip.sig.

      Linux x86-64

      For the latest version of the Amazon Q command line, use the following command:

      curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip.sig" -o "q.zip.sig"

      For a specific version of the Amazon Q command line, replace the latest with the version number. For this example the path for version 1.1.0 would be /1.1.0/q-linux-x86_64.zip.sig, resulting in the following command:

      curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/1.1.0/q-x86_64-linux.zip.sig" -o "q.zip.sig"

      Linux ARM (aarch64)

      For the latest version of the Amazon Q command line, use the following command:

      curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip.sig" -o "q.zip.sig"

      For a specific version of the Amazon Q command line, replace the latest with the version number. For this example the path for version 1.1.0 would be /1.1.0/q-linux-aarch64.zip.sig, resulting in the following command:

      curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/1.1.0/q-aarch64-linux.zip.sig" -o "q.zip.sig"

      For a specific version of the Amazon Q command line, replace the latest with the version number. For this example the path for version 1.1.0 would be /1.1.0/q-linux-aarch64.zip.sig, resulting in the following command:

      curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/1.1.0/q-aarch64-linux.zip.sig" -o "q.zip.sig"

    5. Verify the signature, passing both the downloaded .sig and .zip file names as parameters to the gpg command.

      gpg --verify q.zip.sig q.zip

      The output should look similar to the following:

      gpg: Signature made Wed 24 Apr 2024 12:08:49 AM UTC
gpg:                using EDDSA key 9AF60417E82742C9143E03EC50DC7A8DC24C566
gpg: Good signature from "Amazon Q command line Team <q-command line@amazon.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 9AF6 0417 E827 42C9 143E  03EC 50DC 7A8D C24C 5667
      Note

      The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the Amazon Q for command line PGP key. For more information, see Web of trust.

  3. Unzip the installer. If your Linux distribution doesn't have a built-in unzip command, use an equivalent to unzip it. The following example command unzips the package and creates a directory named q under the current directory:

    unzip q.zip

  4. Run the install program. The installation command uses a file named install in the newly unzipped q directory. By default, the files are all installed to ~/.local/bin.

    ./q/install.sh

After installing the program, you can configure for remote Linux integration that allows for command line autocomplete to be accessible on remote machines. For more information, see Remote Linux integration.

Ubuntu/Debian (Linux)

Amazon Q for command line is available as a prebuilt deb that you can install manually. The deb is compatible with a variety of Debian style systems. If you encounter issues with Ubuntu, consider AppImage, which should work on most Linux environments.

To install Amazon Q for command line for Linux with Ubuntu/Debian

  1. Download the Amazon Q for command line deb package using the following command:

    curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o amazon-q.deb

    For a specific version of Amazon Q for command line, you can replace ... /latest/ ... in the URL with the version number.

    Note

    Amazon Q for command line follows semantic versioning.

  2. (Optional) Verify the download of Amazon Q for command line for Ubuntu/Debian. For more information, see Verifying your download.

  3. Install Amazon Q for command line using the following apt command:

    sudo apt install -y ./amazon-q.deb

    The apt command installs the binaries q, qterm, and q-desktop under /usr/local/bin.

  4. Open the desktop application using the following command:

    q
    Note

    If the desktop application doesn't open, run q-desktop directly in your terminal to view any output error logs. You can open a support issue by running q issue.

    The deb packages also includes a desktop entry that is installed under /usr/share/applications/amazon-q.desktop. If your environment supports the XDG Desktop Entry specifications, you can open the desktop application by searching for Amazon Q.

  5. Follow the onboarding steps.

  6. Authenticate with Builder ID, or with IAM Identity Center using the start URL provided by your account administrator.

  7. In a new terminal, use the following command:

    q doctor

    Follow any remediation instructions until see the output: ✓ Everything looks good!

AppImage (Linux)

Amazon Q for command line is available as an AppImage, a single file with all dependencies included. It executes on a wide variety of Linux environments. You can set the file executable and you can begin using it.

To install Amazon Q for command line for Linux with AppImage

  1. Download Amazon Q for command line for AppImage. Install the latest version using the following command:

    curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.appimage -o amazon-q.appimage

    For a specific version of Amazon Q for command line, you can replace ... /latest/ ... in the URL with the version number.

    Note

    Amazon Q for command line follows semantic versioning.

  2. (Optional) Verify the download of Amazon Q for command line for AppImage. For more information, see Verifying your download.

  3. Make the downloaded AppImage executable using the following command:

    chmod +x amazon-q.appimage

  4. (Optional) Move the downloaded AppImage to a location on your PATH.

  5. Execute the AppImage and follow the onboarding steps.

    The AppImage bundles an XDG Desktop Entry file that can be installed and managed locally for you if you prefer. If your system supports the XDG Autostart specification, this will enable autostart capabilities, ensuring that the application is run on startup.

    Note

    Your system must have FUSE version 2 installed to run AppImages. For Ubuntu 22 and above, you can install FUSE 2 by using the following command:

    sudo apt install libfuse2
    Note

    If the desktop application doesn't open, try running amazon-q.appimage directly in your terminal to view any output error logs. You can open a support issue in the Amazon Q for command line discussions GitHub repository.

  6. Authenticate with Builder ID, or with IAM Identity Center using the start URL provided by your account administrator.

  7. In a new terminal, use the following command:

    q doctor

    Follow any remediation instructions until you see the output: ✓ Everything looks good!

Alternative Linux builds (musl libc/compatibility build)

For Linux systems that have compatibility issues with the standard glibc builds, you can use alternative builds compiled with musl libc. These builds are particularly useful for the following:

  • Older Linux distribution

  • Systems with older glibc versions

  • Alpine Linux and musl-based distributions

  • SSH environments with limited library supports

Downloading musl builds

You can download the musl builds by appending -musl to the filename in the download URL, resulting in the following command:

https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip

For ARM64/aarch64 systems, you can use the following command:

https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-aarch64-linux-musl.zip

After downloading the musl builds, following the installation steps for ZIP setup. For more information, see ZIP setup for autocomplete support.

Handling glibc version issues

You may encounter errors related to glibc version requirements, such as the following:

Error: version 'GLIBC_2.XX' not found

The issue indicates that your Linux distribution has an older version of glibc than required by the standard Amazon Q CLI build. To address the issue, consider the following: