Amazon Q Developer CLI: AWS-Native Terminal Agent Guide

If you spend most of your day inside a terminal and most of your infrastructure inside AWS, the Amazon Q Developer CLI is the one agent that already knows both. Unlike general coding assistants that learned AWS from documentation, Q ships with deep knowledge of AWS services, IAM, the AWS CLI, and your organisation’s identity provider. This guide is for backend and platform engineers who want a practical walkthrough: installation, authentication, the three modes you actually use, MCP and custom agents, and the trade-offs against Claude Code, Aider, and Gemini CLI. By the end, you’ll know exactly where the Amazon Q Developer CLI shines and where another tool fits better.

What Is Amazon Q Developer CLI?

The Amazon Q Developer CLI is AWS’s official terminal-based AI assistant. It runs inside your shell as a single binary (q) and combines three capabilities: a chat agent that can read and edit files, inline ghost-text autocompletion in your shell, and natural-language to bash translation. Under the hood, it routes to Claude models on Amazon Bedrock and ships with first-class tools for the AWS CLI, file system access, and shell execution.

Crucially, Q is identity-aware in AWS terms. It authenticates either through a free AWS Builder ID or your company’s IAM Identity Center (formerly AWS SSO). That second path is what makes it different from every other terminal agent: when your engineers run q chat, the agent inherits the same SSO permissions they already have for the AWS CLI. No separate API keys, no shadow credentials, no out-of-band billing.

It runs natively on macOS and Linux, plus Windows via WSL. There is also a Windows preview build. Pricing is tiered: a Free tier with monthly chat and inline-suggestion limits, and a Pro tier at roughly $19 per user per month with higher limits, longer context, and code-transformation features.

Why Use an AWS-Native Terminal Agent?

Terminal agents are now common, with Claude Code, Aider, Gemini CLI, and OpenCode all viable choices. The reason to pick the Amazon Q Developer CLI specifically is when your work touches AWS often enough that cloud literacy matters more than raw coding intelligence.

For instance, asking a generic agent to “tighten the IAM role this Lambda function assumes” usually produces a plausible but generic policy. Q, by contrast, can call aws iam get-role, read the existing policy, check what AWS API actions the function actually invokes in the source, and propose a least-privilege replacement. That feedback loop only works when the agent is comfortable hitting AWS APIs as a first-class tool, not as a foreign integration.

The same applies to CloudWatch logs, Step Functions definitions, S3 lifecycle rules, and Bedrock model access. Q treats these as native verbs, not exotic integrations.

Installing the Amazon Q Developer CLI

Installation depends on your operating system, but it’s a single binary in every case. On macOS, the easiest path is the official DMG installer or Homebrew:

# macOS via Homebrew
brew install --cask amazon-q

# Verify the install
q --version
# Expected output: q 1.x.y (build ...)

On Linux (Debian, Ubuntu, Fedora, Amazon Linux), you can use the package managers AWS publishes:

# Debian/Ubuntu
curl --proto '=https' --tlsv1.2 -sSf \
  https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o /tmp/amazon-q.deb
sudo apt install -y /tmp/amazon-q.deb

# Verify
q doctor

q doctor is the diagnostics command. It checks shell integration, login state, daemon status, and PATH configuration. Run it any time the CLI behaves oddly.

For Windows, the recommended path is WSL2 with the Linux install steps above. A native Windows build exists in preview, but at the time of writing, the WSL path is more stable for daily use.

After installation, two things happen:

1. The q binary is added to your PATH.
2. A small daemon starts, providing inline shell suggestions (ghost text). It hooks into bash, zsh, and fish.

If you don’t want the inline daemon, run q settings app.shellSuggestions false. The chat agent still works without it.

Authenticating With AWS Builder ID or IAM Identity Center

Authentication is where the Amazon Q Developer CLI starts to diverge from other terminal agents. Run:

q login

You’ll be prompted to choose between two identity providers:

1. AWS Builder ID — a free personal identity tied to your email. Good for solo developers, side projects, and learning.
2. IAM Identity Center — your organisation’s SSO. You’ll enter a start URL (something like https://acme.awsapps.com/start) and a region. Q opens a browser for the device authorisation flow, the same flow aws sso login uses.

Once authenticated, the token lives in ~/.local/share/amazon-q/ (Linux/macOS) and refreshes automatically until your SSO session expires. Importantly, Q’s permissions for AWS API calls are the same permissions your IAM Identity Center user has. If your role can describe Lambda functions but not delete them, neither can the agent.

This permission inheritance is a feature, not a bug. It means you can let Q run AWS commands inside your daily work without setting up service accounts or rotating API keys. To see who you’re authenticated as, run:

q whoami

For teams already using IAM Identity Center, this also makes auditing simple: every API call Q makes appears in CloudTrail under the same identity that ran the command.

The Three Modes You Actually Use

The Amazon Q Developer CLI is technically one binary, but in practice you’ll use three distinct modes daily.

1. Chat Mode With File Editing

Run q chat to enter an interactive session. Inside the session, the agent has tools for reading files, writing files, executing shell commands, and calling the AWS CLI. A typical session looks like this:

$ q chat
> read the lambda function in src/handlers/checkout.ts and tell me which IAM
> permissions it actually needs

[Q reads the file, identifies dynamodb:PutItem, sqs:SendMessage, sns:Publish calls]

The function needs:
- dynamodb:PutItem on the orders table
- sqs:SendMessage on the order-events queue
- sns:Publish on the customer-notifications topic

Want me to draft a least-privilege role policy?

You can also pass an initial prompt non-interactively: q chat "summarise the README".

Inside chat, slash commands control the session: /tools lists active tools and their trust level, /context manages which files and directories are loaded into context, /compact summarises history when the conversation gets long, and /quit exits.

2. Inline Shell Autocomplete

When the daemon is running, Q shows ghost text in your shell as you type. For example, typing git rebase might suggest git rebase --interactive --autosquash HEAD~5 based on what you’ve been doing. Press the right-arrow key to accept.

This is genuinely useful for AWS CLI commands, where flag combinations are unforgiving. Typing aws s3api put-bucket will surface the full incantation including --bucket, --acl, and JSON document flags.

3. Natural-Language to Bash Translation

Run q translate "find all log files larger than 100MB modified in the last week" and Q produces the corresponding find command, then asks whether to execute. This is faster than chat for one-shot shell tasks.

q translate "show me the top 10 largest files in this directory"
# Suggested: du -ah . | sort -rh | head -n 10
# Run? [y/N]:

Translation never executes without confirmation, which is the right default.

AWS-Native Tools Built Into the Agent

The reason to choose the Amazon Q Developer CLI over a generic agent is the use_aws tool. It is a built-in tool that Q uses to call the AWS CLI on your behalf, with three useful properties:

1. It uses your active SSO session, no extra setup.
2. It defaults to read-only operations unless you explicitly trust write operations.
3. It can chain calls across services in a single reasoning step.

For example, the prompt “what’s the cold-start P99 for the checkout-prod Lambda over the past 24 hours?” triggers a chain like:

• aws lambda get-function-configuration --function-name checkout-prod (find ARN, region, log group)
• aws cloudwatch get-metric-statistics (query Init Duration metric)
• aws logs filter-log-events (find REPORT lines and parse Init Duration)

Q assembles those results into a single answer, with a chart-style summary. To inspect or restrict which AWS actions Q can take, run /tools inside chat:

> /tools
trusted: fs_read, use_aws (read-only)
untrusted: fs_write, execute_bash, use_aws (write)

You can promote write tools to trusted with /tools trust use_aws, but the safer default is to leave write operations needing confirmation. For serverless applications where one bad command could delete production resources, the per-action approval prompt is what keeps the agent useful instead of dangerous.

MCP Servers and Custom Agents

Like other modern terminal agents, the Amazon Q Developer CLI supports the Model Context Protocol (MCP). MCP is a standard for plugging external tools into AI agents — Postgres readers, GitHub clients, Jira integrations, and so on.

Q reads MCP configuration from ~/.aws/amazonq/mcp.json (global) or .amazonq/mcp.json (per project). A minimal example wiring a Postgres MCP server looks like this:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://localhost:5432/app_dev"
      }
    }
  }
}

After restart, /tools inside chat shows the new tools the Postgres server exposes (typically query, schema, and list_tables).

Beyond MCP, Q supports custom agents — saved profiles with a specific tool set, system prompt, and context. Drop a YAML file in .amazonq/agents/ such as:

name: aws-cost-optimizer
description: Read-only cost analysis assistant
tools:
  - fs_read
  - use_aws
prompt: |
  You are an AWS cost optimisation specialist. You may only read AWS resources.
  Focus on Cost Explorer, Compute Optimizer, and Trusted Advisor data.
  Never suggest changes that require write permissions.
context:
  - infra/**/*.tf
  - infra/**/*.yaml

Then launch with q chat --agent aws-cost-optimizer. Custom agents are how you build narrow, safe assistants for specific jobs (cost analysis, security reviews, IAM audits) without manually re-prompting each time.

When to Use Amazon Q Developer CLI

• Your team’s primary cloud is AWS and you already use IAM Identity Center
• You want a terminal agent that inherits SSO permissions instead of using static API keys
• Your work mixes code with frequent AWS operations (Lambda, CloudWatch, IAM, S3, Bedrock)
• You need an audit trail that ties agent actions back to a real AWS identity in CloudTrail
• You want inline shell autocompletion for AWS CLI flag combinations

When NOT to Use Amazon Q Developer CLI

• Your stack is heavily on GCP, Azure, or Cloudflare — choose a cloud-neutral agent instead
• You need the latest frontier-model coding intelligence (Claude Code or OpenCode often feel sharper on pure code tasks)
• You’re doing offline development without internet access
• You require the agent to drive a browser, like Claude’s Computer Use, which Q does not currently expose
• You need a fully local, open-weights agent for compliance reasons (consider self-hosted Aider or OpenCode)

Common Mistakes With Amazon Q Developer CLI

The mistakes that bite teams the most are not technical — they’re trust-model mistakes.

First, blanket-trusting all tools because the confirmation prompts feel slow. Once you run /tools trustall, the agent can write files, execute arbitrary bash, and call AWS write APIs without asking. In a production-aware shell, that’s how someone ends up explaining why the staging RDS instance was deleted at 2 AM. Trust per-tool, not all-at-once.

Second, ignoring the boundary between Builder ID and IAM Identity Center. Engineers sometimes log in with their personal Builder ID on a work machine, which means agent actions don’t show up in CloudTrail with their corporate identity. Always check q whoami before doing anything that touches shared infrastructure.

Third, dumping the entire repository into context with /context add **/*. Q has a generous context window but not an infinite one, and large irrelevant context degrades reasoning quality. Be specific: add the directories Q needs, not your whole monorepo.

Fourth, treating the agent as a code review substitute. Q can produce confident-looking IAM policies that are technically valid and operationally wrong. Always pair with the practical IAM breakdown and a human reviewer for anything that affects production permissions.

Real-World Scenario: Lambda Cold-Start Investigation

A small platform team running 40-50 Lambda functions on AWS notices that one checkout function has elevated latency, but only intermittently. The on-call engineer opens a terminal and runs q chat, then asks: “Investigate cold-start patterns for the checkout-prod Lambda over the past 48 hours and compare to the previous week.”

Q, with read-only AWS tools trusted, calls Lambda for configuration metadata, queries CloudWatch metrics for Init Duration, pulls the relevant CloudWatch Logs for REPORT lines, and assembles a textual summary: cold-start P99 has roughly doubled, primarily on Mondays at 9 AM regional time, correlated with a deployment that increased the package size by around 40%.

The engineer doesn’t need to remember CLI flags or write a script. Q ran the investigation in roughly two minutes of conversation, with each AWS call attributed to the engineer’s Identity Center identity in CloudTrail. The follow-up — provisioning a small amount of provisioned concurrency or trimming the deployment package — is then a normal code change, made with Q’s editing tools or a regular pair-programming session.

The same workflow with a non-AWS-native agent would mean copy-pasting AWS CLI commands by hand, switching between agent and shell, and losing the conversational flow.

How Amazon Q Developer CLI Compares

A short comparison table for engineers picking among terminal agents:

Feature	Amazon Q Developer CLI	Claude Code	Aider	Gemini CLI
AWS-native tools	Yes (built-in)	Via MCP	Via MCP	Via MCP
SSO/Identity Center auth	Yes	No	No	No
MCP support	Yes	Yes	Limited	Yes
Inline shell autocomplete	Yes	No	No	No
Free tier	Yes	Limited	Open-source	Yes
Best at pure code tasks	Good	Excellent	Excellent	Good

If pure code intelligence is the priority, Claude Code remains the strongest option for most teams. But for AWS-heavy work where identity, audit, and AWS API fluency matter, the Amazon Q Developer CLI is the easier fit.

Conclusion: Picking the Right Terminal Agent for AWS Work

The Amazon Q Developer CLI is the right choice when your work lives inside AWS and you want an agent that respects your existing identity model instead of bolting a new one on top. The Free tier is generous enough to evaluate seriously, and the Pro tier is reasonably priced for teams that depend on it daily.

Install it with the OS-specific package, log in with q login, run q doctor to confirm the daemon is healthy, then spend an afternoon with q chat on a real task — a Lambda investigation, an IAM cleanup, a CloudWatch dashboard query — to see whether AWS-native tooling moves the needle for your workflow. If you also want a sharper general-purpose coding agent in your toolbox, pair the Amazon Q Developer CLI with Claude Code and use each for what it does best.