This article follows the official documentation. We haven’t tested this tool for a hands-on review.
A coding agent with shell access to an AWS environment can use the AWS Command Line Interface (AWS CLI) to query AWS services. The CLI runs in a terminal and sends API requests with the credentials and permissions configured for that shell.
An agent can use it, for example, to inspect EC2 instances in a region and return a concise JSON summary. The command runs locally, but the request goes to AWS and the response describes live account resources. Use a profile tied to an AWS Identity and Access Management (IAM) role with only the permissions the agent needs. Review commands that change resources before running them.
Install and configure the CLI
Install AWS CLI version 2 using the official installation instructions. Check that the shell can find it with:
aws --version
The command checks the local installation; it does not contact AWS. To configure access through AWS IAM Identity Center, which lets you sign in to an organization’s AWS accounts, create a named profile (a saved set of CLI settings) and sign in:
aws configure sso --profile agent-readonly
aws sso login --profile agent-readonly
Follow the prompts to select an account and authorized role. The selected role's IAM permissions determine what the agent can do; agent-readonly is just the profile name. Keep credentials in the normal AWS credential setup rather than putting them in an agent prompt. AWS documents setup options in its CLI configuration instructions.
Inspect EC2 instances
This command asks Amazon Elastic Compute Cloud (EC2), AWS’s virtual server service, for instance details in the us-east-1 region. It then uses --query to select each instance’s ID and state:
aws ec2 describe-instances \
--profile agent-readonly \
--region us-east-1 \
--query 'Reservations[].Instances[].{InstanceId:InstanceId,State:State.Name}' \
--output json
The CLI uses --profile to load configured credentials and --region to send the request to the selected AWS region. The query uses JMESPath, a language for selecting and shaping JSON data. --output json asks the CLI to print the selected result as JSON, which an agent can parse or pass to another local command.
The CLI makes a network request to AWS; it does not change an instance. If AWS returns an empty list, the response contains no matching instances for the selected region. If the request fails, the error can point to unavailable credentials. It can also indicate an incorrect region. A missing permission is another possible cause. The role must be allowed to describe EC2 instances for this request to succeed.
A realistic prompt for an agent is: “Use the agent-readonly profile to list EC2 instance IDs and states in us-east-1. Run only read-only commands, and summarize the JSON response without changing AWS resources.” The prompt does not grant permissions. AWS still checks the role attached to the profile.
Review commands that change resources
AWS CLI commands can also create, update, or delete cloud resources. Those commands send requests to AWS. AWS applies the requested changes if the caller has permission. Before you let an agent run a write command, inspect the command and check which account, region, and resource it affects. Do not assume a preview mode exists for every command.
Amazon Q Developer offers a separate q translate command that turns natural-language requests into AWS CLI commands. AWS’s example of natural-language translation shows that generated commands can be incomplete or incorrect and need review. The feature is documented for macOS and Linux and requires an AWS Builder ID or IAM Identity Center. An agent can call AWS CLI directly without using that translation feature.