Amazon Q Developer CLI: Complete Guide for DevOps and Development Teams

1. Introduction & Benefits Analysis#

What is Amazon Q Developer CLI#

Amazon Q Developer CLI is a generative AI-powered conversational assistant that revolutionizes command-line development workflows. Unlike traditional AWS CLI tools, Amazon Q Developer CLI combines natural language processing with direct access to AWS services, enabling developers to interact with their infrastructure through conversational interfaces. The tool integrates contextual information from your local development environment, providing enhanced understanding of your specific use case and delivering relevant, context-aware responses.

Key Differences from Other AWS CLI Tools#

🧠 Brain Mode: Key Differentiators

Amazon Q Developer CLI stands apart from traditional AWS CLI tools in several fundamental ways. While the standard AWS CLI requires memorizing specific command syntax and parameters, Amazon Q Developer CLI accepts natural language instructions and translates them into executable commands. This represents a paradigm shift from command-based interfaces to conversation-based development workflows.

The tool’s AI agent capabilities allow it to understand context, maintain conversation history, and provide iterative improvements based on feedback. Unlike static CLI tools that execute single commands, Amazon Q Developer CLI can perform multi-step operations, analyze outputs, and make intelligent decisions about next steps.

Amazon Q Developer CLI supports hundreds of popular command-line tools including git, npm, docker, and aws, providing IDE-style autocompletion and contextual suggestions. The enhanced CLI agent, powered by Claude 3.7 Sonnet, can read and write files locally, query AWS resources, and create code iteratively based on user feedback.

Integration Capabilities with Existing AWS Toolchain#

The CLI integrates seamlessly with existing AWS profiles and credentials, supporting both AWS Builder ID authentication for free tier usage and IAM Identity Center integration for enterprise Pro tier subscriptions. It works alongside traditional AWS CLI installations, respecting existing profile configurations and credential management.

Amazon Q Developer CLI features Console-to-Code functionality that records AWS Management Console actions and generates corresponding CLI commands or Infrastructure as Code templates in multiple formats including CDK Java, Python, TypeScript, and CloudFormation JSON/YAML. This bridges the gap between console-based prototyping and production-ready automation code.

Performance Improvements and Productivity Gains#

Internal Amazon studies demonstrate significant productivity improvements with Amazon Q Developer CLI usage:

• 80% faster development tasks across common software development workflows
• 40% boost in developer productivity through AI-assisted code generation and debugging
• Amazon engineers upgraded 50% of their production Java systems using the tool, saving an estimated 4,500 developer-years of effort and $260M in annualized efficiency gains

The tool optimizes AWS operations and cloud cost efficiency by providing intelligent recommendations for resource utilization and suggesting cost-effective alternatives during infrastructure provisioning.

2. Installation & Setup Guide#

macOS Installation#

Method 1: Direct Download

1. Download the macOS installer (.dmg file) from the official AWS documentation page
2. Open the downloaded .dmg file
3. Drag the Amazon Q app into your Applications folder
4. Launch the application and follow the setup wizard

Method 2: Homebrew Installation

brew install amazon-q

Post-Installation Setup for macOS:

1. Enable shell integrations when prompted
2. Grant accessibility permissions in System Settings → Privacy & Security → Accessibility
3. Complete authentication setup using your AWS Builder ID or IAM Identity Center credentials

Linux Installation#

Ubuntu/Debian Package Installation:

# Update package list
sudo apt update

# Install required dependencies
sudo apt install libfuse2 curl unzip

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

# Install the package
sudo apt install -y ./amazon-q.deb

AppImage Installation (GUI Required):

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

# Make executable
chmod +x amazon-q.appimage

# Run the AppImage
./amazon-q.appimage

Zip File Installation (Headless Environments):

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

# Extract and install
unzip q.zip
cd q
chmod +x install.sh
./install.sh

# Source your shell configuration or restart terminal
source ~/.bashrc  # or ~/.zshrc for zsh users

Windows Installation (via WSL)#

Amazon Q Developer CLI does not have native Windows support as of June 2025, requiring Windows Subsystem for Linux (WSL) for installation.

Step 1: Install WSL

wsl --install

Step 2: Launch Ubuntu Environment

wsl -d Ubuntu

Step 3: Install Amazon Q Developer CLI in WSL

# Navigate to home directory
cd
pwd  # Should show /home/your-username

# Download installer
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

# Install unzip if needed
sudo apt install unzip

# Extract and install
unzip q.zip
cd q
chmod +x install.sh
./install.sh

# Restart shell
bash

Authentication Setup and Configuration#

AWS Builder ID Authentication (Free Tier):

q login

Select “Use for Free with Builder ID” when prompted. This opens a browser window for authentication. The Builder ID provides access to free tier features without requiring an AWS account.

IAM Identity Center Authentication (Pro Tier): For Pro tier subscriptions, organizations must configure IAM Identity Center and create appropriate permission sets. Users authenticate using their organization’s start URL provided by AWS administrators.

Initial Configuration and Profile Management#

Verify Installation:

q --version
q doctor  # Diagnoses configuration issues

Configure Editor Preference:

# Set preferred editor for multi-line prompts
export EDITOR=nano  # or vim, code, etc.

# Make permanent by adding to shell config
echo 'export EDITOR=nano' >> ~/.bashrc

Integration Settings:

# Enable/disable inline completions
q inline enable
q inline disable

# Configure MCP server timeout
q settings mcp.initTimeout 5000  # 5 seconds

Integration with Existing AWS CLI Profiles#

Amazon Q Developer CLI respects existing AWS CLI profiles and credentials. It uses the same credential resolution order as the standard AWS CLI:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. AWS credentials file (~/.aws/credentials)
3. AWS config file (~/.aws/config)
4. IAM roles for EC2 instances
5. IAM roles for ECS tasks
6. IAM roles for Lambda functions

# Use specific AWS profile
export AWS_PROFILE=my-profile
q chat "List S3 buckets in us-west-2"

# Or specify profile in conversation
q chat "Using the production profile, show me EC2 instances"

3. AWS Infrastructure Automation#

Practical Examples for Common AWS Infrastructure Tasks#

EC2 Instance Management:

q chat "Launch a new t3.micro EC2 instance in us-east-1 with Amazon Linux 2"

Amazon Q Developer CLI will generate and execute the appropriate AWS CLI commands, handling subnet selection, security group configuration, and key pair management based on your account’s existing resources.

S3 Bucket Operations:

q chat "Create an S3 bucket with versioning enabled and set up lifecycle policies to transition objects to IA after 30 days"

RDS Database Deployment:

q chat "Deploy a MySQL RDS instance with Multi-AZ enabled and automated backups configured for 7-day retention"

Infrastructure as Code (IaC) Integration#

CloudFormation Integration: Amazon Q Developer CLI can generate CloudFormation templates based on natural language descriptions:

q chat "Generate a CloudFormation template for a three-tier web application with ALB, Auto Scaling Group, and RDS"

The tool generates both JSON and YAML CloudFormation templates, including:

• Resource definitions with appropriate properties
• Parameter sections for customization
• Output sections for cross-stack references
• Proper dependency management

CDK Integration:

q chat "Create a CDK Python stack for a serverless application with API Gateway, Lambda, and DynamoDB"

Generates CDK code in multiple languages:

• TypeScript
• Python
• Java
• C#/.NET

Console-to-Code Workflow:

1. Perform actions in AWS Management Console
2. Use Console-to-Code to record actions
3. Generate equivalent CLI commands or IaC templates:

# After recording console actions
q chat "Convert my recorded console actions to Terraform configuration"

Automated Deployment Pipelines and CI/CD Integration#

GitHub Actions Integration:

name: Deploy with Amazon Q
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Amazon Q CLI
        run: |
          curl -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip -o q.zip
          unzip q.zip && ./q/install.sh
      - name: Deploy Infrastructure
        run: |
          q chat "Deploy the infrastructure defined in ./infra/ directory"

AWS CodePipeline Integration: Amazon Q Developer CLI can generate CodePipeline configurations and integrate with existing CI/CD workflows:

q chat "Create a CodePipeline that builds my Node.js app from GitHub and deploys to ECS"

Resource Provisioning and Management Workflows#

Multi-Environment Management:

# Development environment setup
q chat "Create a development environment with smaller instance types and single-AZ deployment"

# Production environment setup
q chat "Create a production environment with high availability, auto-scaling, and monitoring"

Resource Tagging and Organization:

q chat "Apply consistent tagging strategy across all resources with Environment, Project, and Owner tags"

Cost Optimization Automation Strategies#

Right-Sizing Recommendations:

q chat "Analyze my EC2 instances and recommend right-sizing opportunities"

Reserved Instance Analysis:

q chat "Analyze my usage patterns and recommend Reserved Instance purchases"

Automated Cleanup:

q chat "Identify and clean up unused EBS volumes, unattached Elastic IPs, and outdated AMIs"

4. Application Development Features#

Code Generation and Scaffolding Capabilities#

Amazon Q Developer CLI excels at generating complete application scaffolds and boilerplate code. The enhanced CLI agent can create entire project structures based on natural language descriptions:

Web Application Scaffolding:

q chat "Build a simple fact checking app"

This command generates:

• Complete project structure with appropriate directories
• Package.json with necessary dependencies
• Basic HTML templates and CSS styling
• JavaScript/Python backend code with API endpoints
• Database schema and migration files
• README documentation with setup instructions

Microservice Architecture Generation:

q chat "Create a microservices architecture with user authentication, product catalog, and order processing services using Node.js and Docker"

Integration with Popular IDEs and Development Environments#

VS Code Integration: While Amazon Q Developer CLI operates from the terminal, it integrates seamlessly with IDE workflows:

# Open current project in VS Code and start Q chat
code .
q chat "Analyze this codebase and suggest architectural improvements"

Terminal-Based Development:

# Multi-line prompt composition using /editor command
q chat
Amazon Q> /editor
# Opens your preferred editor for complex prompts

SSH Integration for Remote Development:

# Install SSH integration for remote servers
q integrations install ssh

This enables Amazon Q Developer CLI functionality when working on remote servers via SSH.

Debugging and Troubleshooting Assistance#

Error Analysis and Resolution:

q chat "My Express.js application is throwing 'Cannot read property of undefined' errors. Help me debug this issue."

Amazon Q analyzes error messages, examines code context, and provides:

• Root cause identification
• Step-by-step debugging instructions
• Code fixes with explanations
• Prevention strategies for similar issues

Log Analysis:

q chat "Analyze these CloudWatch logs and identify the cause of high response times"

Performance Troubleshooting:

q chat "My Lambda function is experiencing cold start issues. Optimize it for better performance."

Code Review and Optimization Suggestions#

Automated Code Review:

# Select code and request review
q chat "Review this Python function for security vulnerabilities and performance improvements"

Code Quality Enhancement:

q chat "Refactor this code to follow clean code principles and improve maintainability"

Security Analysis:

q chat "Scan this code for security vulnerabilities and suggest fixes"

Testing Automation and Quality Assurance Features#

Unit Test Generation:

q chat "Generate comprehensive unit tests for this user authentication module"

Integration Test Creation:

q chat "Create integration tests for my REST API endpoints with different scenarios"

Test-Driven Development Support:

q chat "Help me write tests first for a shopping cart feature, then implement the functionality"

5. AWS Infrastructure Visualization#

Creating Architecture Diagrams and Infrastructure Graphs#

Amazon Q Developer CLI can generate AWS architecture diagrams when integrated with MCP (Model Context Protocol) servers. This powerful combination enables automated diagram creation from natural language descriptions:

Setup MCP for Architecture Diagrams:

# Install uv for MCP server management
sudo snap install astral-uv --classic

# Create MCP configuration
mkdir -p ~/.aws/amazonq
cat > ~/.aws/amazonq/mcp.json  /compact

Editor Integration for Complex Prompts:

# Use /editor for multi-line prompts
Amazon Q> /editor

# Set permanent editor preference
export EDITOR=code  # or vim, nano, etc.
echo 'export EDITOR=code' >> ~/.bashrc

Scripting and Automation Workflows#

Automated Deployment Scripts:

#!/bin/bash
# deploy.sh - Automated deployment script

# Start Q session and deploy
q chat --no-interactive --trust-all-tools "
Deploy the application in ./src directory to AWS:
1. Build the Docker image
2. Push to ECR
3. Update ECS service
4. Verify deployment health
"

Infrastructure Provisioning Automation:

# infrastructure-setup.sh
q chat --no-interactive "
Create production infrastructure:
- VPC with public/private subnets
- Application Load Balancer
- ECS cluster with Fargate
- RDS MySQL with Multi-AZ
- CloudWatch logging and monitoring
"

Integration with Other AWS Services and Third-Party Tools#

GitHub Integration: Amazon Q Developer CLI provides direct GitHub integration for automated workflows:

q chat "Review this pull request and suggest improvements"
q chat "Create a new feature branch and implement user authentication"

Docker Integration:

q chat "Containerize my Python application and create optimal Dockerfile"
q chat "Set up multi-stage Docker build for production deployment"

Terraform Integration:

q chat "Convert my CloudFormation templates to Terraform configuration"
q chat "Generate Terraform modules for reusable infrastructure components"

Security Best Practices and Access Management#

IAM Policy Management:

q chat "Review my IAM policies for least privilege compliance"
q chat "Create role-based access control for my development team"

Security Group Optimization:

q chat "Audit my security groups and recommend improvements"
q chat "Implement network segmentation best practices"

Credential Management:

# Use IAM roles instead of long-term credentials
q chat "Help me configure IAM roles for EC2 instances instead of using access keys"

Performance Optimization Techniques#

Query Optimization:

• Use specific, detailed prompts rather than vague requests
• Provide context about your environment and goals
• Break complex tasks into smaller, focused questions

Resource Efficiency:

# Efficient resource usage
q chat --trust-tools=fs_read,fs_write "Optimize my code for better performance"

Conversation Management:

# Start fresh conversations for different topics
Amazon Q> /clear

# Use context effectively
Amazon Q> /context path/to/relevant/files

7. Pricing & Limitations Analysis#

Detailed Comparison of Free Tier vs. Paid Plans#

Amazon Q Developer Free Tier (Free):

• Code Suggestions: Unlimited in IDE and CLI
• CLI Completions: Free for public CLI tools
• Chat Interactions: 50 interactions per month in IDE
• Software Development Agents: 10 invocations per month
• Code Transformation: 1,000 lines of code per month
• AWS Account Queries: 25 queries per month
• Console Error Diagnosis: Included
• License Reference Tracking: Included

Amazon Q Developer Pro Tier ($19/month per user):

• All Free Tier Features: Plus enhanced capabilities
• Chat Interactions: Unlimited in IDE
• Software Development Agents: Unlimited invocations
• Code Transformation: 4,000 lines of code per month
• AWS Account Queries: Unlimited
• Generative SQL: 1,000 queries per month
• Enterprise Access Controls: IAM Identity Center integration
• Customization: Adapt to your codebase for better suggestions
• Additional Charge: $0.003 per line for Java transformation beyond monthly limit

Feature Limitations and Usage Quotas#

Free Tier Limitations:

• Limited monthly interactions may restrict heavy usage
• AWS account resource queries capped at 25 per month
• Code transformation limited to 1,000 lines monthly
• Content may be used for service improvement

Pro Tier Quotas:

• Most features have high or unlimited usage limits
• Code transformation pooled at account level (4,000 lines/month)
• Some internal quotas exist (e.g., 30 software development agent invocations/month)
• No direct upgrade path from Builder ID to Pro tier - requires new subscription

Cost-Benefit Analysis for Different Team Sizes#

Individual Developers:

• Free Tier: Suitable for occasional use, personal projects, learning
• Pro Tier ($19/month): Cost-effective for professional developers with regular AI assistance needs

Small Teams (2-10 developers):

• Monthly Cost: $38-$190 for Pro tier
• ROI Calculation:
  • Average developer hourly cost: $50-$100
  • Time savings: 5-6 hours per week per developer
  • Monthly savings: $1,000-$2,400 per developer
  • ROI: 500-1,200% return on investment

Enterprise Teams (50+ developers):

• Monthly Cost: $950+ for Pro tier
• Benefits:
  • Standardized development practices
  • Reduced onboarding time for new developers
  • Consistent code quality across teams
  • Enterprise security and access controls

Migration Path from Free to Paid Plans#

Important Migration Considerations:

• No direct upgrade path from Builder ID to Pro tier
• Users must create new IAM Identity Center accounts for Pro access
• Existing conversations and settings don’t transfer
• Organizations need IAM Identity Center setup before Pro activation

Migration Steps:

1. Set up IAM Identity Center in AWS account
2. Subscribe to Amazon Q Developer Pro in AWS console
3. Create user groups and assign permissions
4. Users sign out of Builder ID sessions
5. Users authenticate with IAM Identity Center credentials

Alternative Tools Comparison#

Primary Alternatives:

• ChatGPT: General-purpose AI assistant, not AWS-specific
• GitHub Copilot: IDE-focused, limited CLI capabilities
• Cody (Sourcegraph): Code-centric, enterprise context awareness
• Windsurf Editor: IDE with built-in AI assistance

When to Choose Amazon Q Developer CLI:

• Heavy AWS infrastructure management
• Need for CLI-based AI assistance
• Integration with existing AWS toolchain
• Cost optimization and AWS best practices guidance
• Console-to-Code workflow requirements

8. Real-World Workflow Integration#

DevOps Pipeline Integration Examples#

CI/CD Pipeline Enhancement:

# In GitHub Actions workflow
- name: Deploy with Amazon Q
  run: |
    q chat --no-interactive --trust-all-tools "
    Deploy application to staging environment:
    1. Run test suite
    2. Build Docker image
    3. Deploy to ECS staging cluster
    4. Run smoke tests
    5. If successful, promote to production
    "

Infrastructure Drift Detection:

# Scheduled drift detection script
#!/bin/bash
q chat --no-interactive "
Check for infrastructure drift:
1. Compare current AWS resources with Terraform state
2. Identify any manual changes
3. Generate drift report
4. Send alert if discrepancies found
"

Developer Workflow Optimization Scenarios#

Feature Development Workflow:

# Start new feature
q chat "Create a new feature branch for user authentication and set up basic structure"

# During development
q chat "Review my authentication code for security best practices"

# Pre-commit checks
q chat "Run code quality checks and fix any issues before committing"

Code Review Acceleration:

# Automated code review
q chat "Analyze this pull request for potential issues, security vulnerabilities, and performance improvements"

Team Collaboration Features and Setup#

Shared Configuration Management:

// .q-config.json - Team-shared configuration
{
  "profiles": {
    "development": {
      "aws_profile": "dev",
      "default_region": "us-west-2"
    },
    "production": {
      "aws_profile": "prod",
      "default_region": "us-east-1"
    }
  },
  "trusted_tools": ["fs_read", "fs_write", "use_aws"],
  "editor": "code"
}

Team Best Practices:

# Standardized deployment commands
alias deploy-dev="q chat --profile development --trust-all-tools 'Deploy to development environment'"
alias deploy-prod="q chat --profile production 'Deploy to production with approval checks'"

Monitoring and Alerting Integration#

Proactive Monitoring Setup:

q chat "Set up comprehensive monitoring for my web application including:
- Application performance metrics
- Infrastructure health checks
- Custom business metrics
- Automated alerting for anomalies"

Alert Response Automation:

# Incident response script
q chat "Investigate the high CPU alert:
1. Check CloudWatch metrics for the affected instances
2. Analyze application logs for errors
3. Suggest immediate mitigation steps
4. Create incident report"

Incident Response and Troubleshooting Workflows#

Systematic Troubleshooting Process: Amazon Q Developer CLI provides structured incident response capabilities:

q chat "Our production NGINX application is experiencing 502 Gateway Timeout errors. Help investigate and diagnose the issue."

The tool systematically:

1. Discovers infrastructure components (ECS clusters, services, tasks)
2. Checks service health and status
3. Analyzes logs across multiple services
4. Identifies root causes through correlation
5. Provides step-by-step remediation guidance
6. Validates fixes and confirms resolution

Automated Log Analysis:

q chat "Analyze the last hour of CloudWatch logs to identify the cause of increased error rates"

Performance Issue Resolution:

q chat "My database is experiencing slow query performance. Help identify bottlenecks and optimize queries."

9. Quick Reference & Troubleshooting#

Essential Commands Reference#

Common Troubleshooting Issues#

Installation Issues:

Terminal not detecting q command

# Restart terminal or source shell config
source ~/.bashrc  # or ~/.zshrc

Permission denied errors on Linux

chmod +x install.sh
./install.sh

Authentication Issues:

Bearer token refresh errors

rm ~/.aws/qcodetransform/credentials.json
qct transform  # Re-authenticate

Builder ID to Pro tier transition

• Cannot directly upgrade from Builder ID to Pro tier
• Must create new IAM Identity Center account
• Sign out of existing session before authenticating with Pro credentials

Performance Issues:

Slow response times

• Use more specific prompts
• Break complex requests into smaller tasks
• Check internet connectivity and AWS service status

CLI integration not working after autostart

• Manually restart the Amazon Q CLI service
• Check accessibility permissions on macOS
• Verify shell integration installation

Links to Official Documentation#

• Amazon Q Developer User Guide ↗
• Command Line Installation Guide ↗
• Amazon Q Developer Pricing ↗
• GitHub Repository ↗
• CLI Command Reference ↗
• MCP Integration Guide ↗