Sarvar Nadaf for AWS Community Builders

Posted on May 19 • Edited on Jul 7

🤖 AI Meets CLI: Let Amazon Q CLI Do the Work 🚀

#aws #ai #beginners #tutorial

👋 Hey there, tech enthusiasts!

I'm Sarvar, a Cloud Architect with a passion for transforming complex technological challenges into elegant solutions. With extensive experience spanning Cloud Operations (AWS & Azure), Data Operations, Analytics, DevOps, and Generative AI, I've had the privilege of architecting solutions for global enterprises that drive real business impact. Through this article series, I'm excited to share practical insights, best practices, and hands-on experiences from my journey in the tech world. Whether you're a seasoned professional or just starting out, I aim to break down complex concepts into digestible pieces that you can apply in your projects.

Let's dive in and explore the fascinating world of cloud technology together! 🚀

The way we write and test code is changing fast. Instead of typing long lines of code from scratch, we now have tools that can understand natural language and generate working code for us. One such powerful tool is Amazon Q CLI, a command line interface powered by artificial intelligence, built by AWS. This tool acts like a smart assistant right inside your terminal. You can ask it to write, debug, and deploy code just by describing what you want in plain English.

In this article, we will learn how to set up Amazon Q CLI locally on your computer. Whether you're building a prototype, learning AWS services, or experimenting with automation, Amazon Q CLI can save time and boost your productivity.

What Are We Doing?

In this guide, we’ll walk through the installation and setup of Amazon Q CLI on an Amazon Linux 2 machine (or any compatible Linux environment). The goal is to enable you to interact with AWS services using plain English directly from your terminal.

Once installed, Amazon Q CLI becomes your AI-powered cloud assistant that understands natural language and turns your commands into real, working cloud solutions.

With Amazon Q CLI, you can:

Generate code files like HTML, CSS, JavaScript, Python, and more
Build and deploy full-stack applications to AWS
Debug AWS CLI errors and broken workflows
Write Infrastructure as Code using tools like CloudFormation or Terraform
Analyze logs and troubleshoot security issues (e.g., IAM permission errors)

The best part? You don’t need to be an AWS or DevOps expert to get started. Amazon Q CLI walks you through each step, helping you build and learn simultaneously. Whether you're a developer, cloud engineer, or someone exploring AWS, this tool simplifies cloud development and boosts productivity.

How Will This Help You?

Amazon Q CLI can significantly enhance your daily workflow. Instead of spending time searching documentation or copying code snippets from various sources, you can:

Speed up development by turning ideas into functional code instantly
Stay focused without constantly switching between tabs, docs, and tools
Learn AWS hands-on as the CLI explains and builds alongside you
Troubleshoot faster by pasting error messages and asking for solutions
Deploy smarter by letting Q CLI handle repetitive setup and deployment steps

Think of it as a knowledgeable teammate always available in your terminal, ready to assist whenever you need it.

Step-by-Step: How to Install Amazon Q CLI Locally

Let’s break down the entire installation process. Please note: As of now, Amazon Q CLI is officially supported only on Linux and macOS. For Windows users, the setup requires using WSL (Windows Subsystem for Linux). Ive covered in detailed Both the ways linux as well as windows way in below section.

Step 1: Install the AWS CLI (if not already installed)

Visit the AWS CLI official guide. Download and install the CLI based on your operating system (Windows, macOS, Linux). After installation, verify using:

aws --version

Step 2: Configure the AWS CLI

Once AWS CLI is installed, configure it with your credentials:

aws configure

It will ask you for:

AWS Access Key ID
AWS Secret Access Key
Default Region (e.g., us-east-1)
Default output format (json or yaml)

If you’ve already configured the CLI, it will look like the screenshot above. This links your local machine to your AWS account.

Option 1: Install Amazon Q CLI on Windows Using WSL

Why WSL with Ubuntu Is Required on Windows?

Even though Git Bash supports many Linux like commands on Windows, it is not a full fledged Linux environment. Amazon Q CLI is built for Linux systems and relies on native Linux features such as file system structure, executable formats, and permissions that Git Bash does not fully support. To overcome this limitation, Windows users need to use WSL (Windows Subsystem for Linux), which allows running a real Linux distribution like Ubuntu inside Windows. With WSL and Ubuntu, users get a genuine Linux environment where Amazon Q CLI can be properly installed and executed, ensuring full compatibility and functionality as intended by AWS.

So in a nutshell: Amazon Q CLI is not natively supported on Windows, so you need to use Linux inside Windows via WSL.

Step 1.1: Enable WSL

Open PowerShell as Administrator and run:

wsl --install

Restart your machine if prompted.

Step 1.2: Install Ubuntu

Open Microsoft Store and search for Ubuntu
Click Install, then launch it from the Start menu
Set up a Linux username and password when prompted

Step 2: Install Amazon Q CLI Inside WSL (Ubuntu)

Once inside the Ubuntu terminal:

2.1 Download and Install Amazon Q CLI

curl -O https://amazon-q-cli.s3.amazonaws.com/latest/amazonq-linux.zip
unzip amazonq-linux.zip
sudo mv amazonq /usr/local/bin/
chmod +x /usr/local/bin/amazonq

Ensure the amazonq binary is executable and accessible from any terminal session.

Step 3: Authenticate with Amazon Q CLI

amazonq login

Select “Use for Free with Builder ID”
If you don’t have a Builder ID, sign up with your email
You’ll receive a URL and a verification code
Open the URL, enter the code, and approve the authentication

You’re now ready to start using Amazon Q CLI!
Sure Sarvar! Here's the step-by-step command list to install the Amazon Q Developer CLI on Ubuntu (ideal for EC2, WSL, or local Ubuntu machines).

Option 2: Installing Amazon Q CLI on Amazon Linux 2

If you’re using Amazon Linux 2 whether on an EC2 instance, a local virtual machine, or WSL the installation process is straightforward and does not require additional emulation layers like WSL on Windows. For Ubuntu users on EC2, please follow the steps outlined above. Amazon Q CLI is officially supported on Linux distributions, including Amazon Linux 2. Below are the detailed steps to install and configure it properly.

Step 1: Update Your System

Always start by updating your system packages to ensure you have the latest updates and tools:

sudo yum update -y

Step 2: Install Required Utilities

Make sure curl, unzip, and bash are installed:

sudo yum install -y curl unzip bash

Step 3: Download the Latest Amazon Q CLI

Determine your system architecture (most Amazon Linux 2 instances are x86_64):

uname -m

If the output is x86_64, use the following command to download the latest Amazon Q CLI:

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

If the output is ARM64 use the following command to download the latest Amazon Q CLI:

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

Step 4: Unzip the Downloaded Package

Let's Unzip the zipped file.

unzip q.zip

Step 5: Run the Installer Script as Non-root User

If you're already using the default ec2-user, you can skip this step.

Amazon Q CLI does not support installation as the root user by default. The installer places the CLI inside the user's home directory (~/.local/bin), which is not ideal when logged in as root. Therefore, if you're currently logged in as root, you should create a new non root user and switch to it before proceeding. Create a New User:

sudo adduser yourusername
sudo passwd yourusername

Switch to the New User:

su - yourusername

Step 6: Log in to Amazon Q CLI

Once you're in a non root user session, navigate to the directory where you downloaded the Amazon Q CLI files and run the installer:

./q/install.sh

When prompted, select Yes to allow the script to update your shell configuration. Choose AWS Builder ID as the login method and hit Enter.

Once the installer starts the login process, it will display a URL and verification code. Copy the URL and open it in a browser tab. You'll be redirected to the AWS Builder ID login page:

If you don't have an AWS Builder ID, create one using your email address.

After logging in, you'll be taken to the Authorization Request screen. Click Confirm and Continue.

On the next screen, you'll be asked to grant access to Amazon Q Developer for Command Line. Click Allow Access to complete the setup.

You’ll see a confirmation screen like this:

Return to your terminal, and you’ll see a success message indicating you’re now logged in to Amazon Q CLI.

Step 7: Verify Installation

Check that q command is available:

q --version

What’s Next?

Now that you've successfully installed and logged in to Amazon Q CLI, you're ready to use its powerful features right from your terminal. This tool is designed to respond to natural language prompts, allowing you to skip boilerplate scripting and let Amazon Q do the heavy lifting.

Try your first command:

q chat

Then type a prompt like:

“Create a static website that shows AWS cost optimization tips.”

Amazon Q CLI will automatically generate all the necessary files for your project, such as:

index.html – The homepage layout
style.css – Styling for your webpage
script.js – Any client side interactivity
README.md – Auto documented project summary

Allow action by press t and hit enter.

You’ll get the option to review and confirm each file. And if needed, Amazon Q can even help you deploy the site to AWS (e.g., on an S3 bucket) all guided interactively through the terminal.

Explore More Use Cases with Amazon Q CLI

Amazon Q CLI isn't limited to simple projects. It can help you with a wide range of real world AWS and development tasks, all by interpreting plain English instructions.

1. Build Full-Stack Serverless Applications
Prompt:

“Create a serverless web app using Python backend (Lambda) and HTML frontend. Store user data in DynamoDB.”

What It Does:

Generates Lambda functions with Python code
Builds a basic frontend (HTML/CSS/JS)
Produces infrastructure as code (AWS SAM or CloudFormation)
Guides you through deployment

2. Troubleshoot AWS CLI Errors
Prompt:

“I’m getting AccessDenied when running aws s3 ls. Help me fix this.”

What It Does:

Analyzes the error
Identifies missing IAM permissions
Suggests exact policy updates to resolve the issue

3. Create Custom IAM Policies
Prompt:

“Generate an IAM policy to allow reading from S3 and writing to DynamoDB.”

What It Does:

Crafts a compliant IAM policy document
Explains each permission line-by-line
Highlights overly broad permissions

4. Debug Failing Lambda Functions
Prompt:

“My Lambda function times out. What should I check?”

What It Does:

Suggests reviewing timeout and memory settings
Recommends checking VPC configs or CloudWatch logs
Helps you update your function or its environment

5. Recommend FinOps & Cost Optimization Techniques
Prompt:

“List cost optimization techniques for EC2 and RDS.”

What It Does:

Suggests best practices like using Spot/Reserved Instances, rightsizing, and auto shutdown
Optionally generates a markdown file with all tips for documentation or sharing

6. Describe Architecture Diagrams in Text Format
Prompt:

“Create an architecture diagram description for a serverless app with API Gateway, Lambda, and DynamoDB.”

What It Does:

Produces a text based architecture outline
Can be used with tools like AWS Application Composer or Mermaid.js for visualization

What Q CLI Does?
With Amazon Q CLI, you're no longer limited by scripting expertise or time constraints. Just ask, and build one natural-language command at a time.

Gives a written layout of the architecture
Uses standard terminology to describe each component and connection
Helps you visualize before drawing the actual diagram

Conclusion: Amazon Q CLI marks a significant step toward simplifying cloud development by allowing you to interact with AWS services using natural language. Installing it locally gives you instant access to an intelligent assistant capable of generating code, troubleshooting errors, writing infrastructure templates, and even deploying applications all from your terminal. This tool isn’t just about convenience it’s about transforming how we work. By reducing the time spent on boilerplate code and command syntax, Amazon Q CLI lets you focus more on solving real problems and delivering value. Whether you're a beginner learning AWS or an experienced developer building production workloads, Q CLI adapts to your needs and accelerates your workflow.

📌 Wrapping Up
Thank you for investing your time in reading this article! I hope these insights have provided you with practical value and a clearer understanding of the topic. Your engagement and learning journey matter to me.

💡 What's Next?
Stay tuned for more in-depth articles where we'll explore other exciting aspects of cloud operations, GenAI, DevOps, and data operations. Follow me for weekly content that aims to demystify complex tech concepts and provide actionable insights.

🤝 Let's Connect!
I'd love to hear your thoughts and experiences! Drop your comments below or connect with me on LinkedIn. Your feedback helps me create more valuable content for our tech community.

Happy Learning! 🚀