Using CLI Autocomplete on a remote machine with SSH - Amazon Q Developer
Local macOS IntegrationRemote Linux IntegrationKnown limitations

Using CLI Autocomplete on a remote machine with SSH

When you install Amazon Q for the command line locally, it adds autocomplete for over 500 CLI tools to your existing terminal in your local environment. By enabling SSH integration, you can make CLI autocomplete accessible on remote machines as well.

Local macOS Integration

To enable SSH integration enable the local SSH integrations by running the following command: 

$ q integrations install ssh

Remote Linux Integration

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.

  • The Amazon Q CLI uses glibc 2.34 or newer. It is included by default in most major distributions of Linux released since 2021.

  • We support the Amazon Q CLI on 64-bit versions of recent distributions of Fedora, Ubuntu, and Amazon Linux 2023.

  • Because AWS doesn't maintain third-party repositories, we can’t guarantee that they contain the latest version of the Q CLI.

Install the Amazon Q CLI

  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 CLI 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 CLI installer package .zip files are cryptographically signed using PGP signatures. If there is 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 website.

    2. To create the public key file, create a text file and 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 CLI 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 CLI Team <q-cli@amazon.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

    4. Download the Amazon Q CLI 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 CLI, use the following command block:

      $ 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 CLI, 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:

      q 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 CLI, use the following command block:

      $ 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 CLI, 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 CLI, 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 CLI Team <q-cli@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

  5. Install ssh config integrations. To do this you must edit your sshd_config to add the AcceptEnv and AllowStreamLocalForwarding setting. To edit the sshd_config run:

    $ sudo -e /etc/ssh/sshd_config

    Once you are editing the sshd_config add the following to the end of the config file:

    AcceptEnv Q_SET_PARENT
AllowStreamLocalForwarding yes

    Note, you must also restart the sshd process after installing, if you are using systemd you may run:

    $ sudo systemctl restart sshd

  6. To finish setting up the integrations you must disconnect from the SSH instance and reconnect. Once you do you can login to Q by running:

    $ q login

    To check for any other installation issues run:

    $ q doctor

Known limitations

A known limitation is that if the Amazon Q desktop client is quit while connected to a remote machine via SSH, an error message will print repeatedly by SSH. For example:

connect to /var/folders/tg/u1vx4xfmvqav0oxfa4zfknaxiwmbsbr/T/cwrun/remote.sock port -2 failed: Connection refused

To get rid of the error message, either exit the SSH session and reconnect or restart the Amazon Q desktop client.