AWS Cli Reference

AWS CLI Reference

The AWS Command Line Interface (CLI) is the primary tool for automating, scripting, and managing AWS resources from the command line. It matters when you need to provision infrastructure in a repeatable way, orchestrate deployments across multiple services, or integrate AWS into CI/CD pipelines. Use it when you require consistent, versioned, and idempotent operations across regions, accounts, and environments.

Managing AWS Profiles and Credentials

AWS CLI uses named profiles to manage multiple sets of credentials and configurations. Profiles are stored in ~/.aws/credentials and ~/.aws/config, and are referenced in commands via the --profile flag.

Example credentials file (~/.aws/credentials):

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[staging]
aws_access_key_id = AKIAIOSFODNN7STAGING
aws_secret_access_key = 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
role_arn = arn:aws:iam::123456789012:role/Deployer

[production]
aws_access_key_id = AKIAIOSFODNN7PROD
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYPRODKEY
region = us-east-1
output = json

Example config file (~/.aws/config):

[profile staging]
region = us-west-2
output = table

[profile production]
region = us-east-1
output = json
cli_pager = less

[default]
region = us-east-1
output = json

Commands use profile context via --profile, and the CLI resolves credentials through this hierarchy: --profile, AWS_PROFILE, AWS_DEFAULT_PROFILE, and ~/.aws/config.

Key Gotchas

• The role_arn in a profile triggers automatic role assumption using the sts:AssumeRole API. The CLI automatically fetches session tokens and updates AWS_SESSION_TOKEN, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY environment variables.
• --profile staging can be combined with --region us-west-2 — the latter overrides the config file’s region.
• If a profile lacks aws_secret_access_key, the CLI attempts to assume a role via role_arn and source_profile (if specified).
• aws sts get-caller-identity is the go-to command to verify current credentials and session context.

Working with AWS Services via CLI

The CLI follows the pattern aws <service> <command> [options], with commands structured as verb-noun (e.g., create-stack, describe-instances, put-object). All commands accept --region, --output, --query, and --profile as global flags.

Creating and Managing EC2 Instances

Launch a single EC2 instance:

aws ec2 run-instances \
  --image-id ami-0abcdef1234567890 \
  --instance-type t3.micro \
  --key-name my-key-pair \
  --security-groups default \
  --count 1 \
  --profile staging \
  --region us-west-2 \
  --output json \
  --query 'Instances[0].InstanceId'

• --image-id must be a valid AMI ID (e.g., ami-0abcdef1234567890).
• --instance-type uses standard AWS instance naming (e.g., t3.micro, m5.large).
• --key-name references an existing EC2 key pair.
• --security-groups accepts a list; multiple groups are comma-separated.

Wait for instance to be running:

aws ec2 wait instance-status-ok \
  --instance-ids i-1234567890abcdef0 \
  --profile staging \
  --region us-west-2

• wait commands block until a condition is met. They use polling with exponential backoff.
• instance-status-ok waits for Status Check and System Status to pass.
• The command returns immediately when the condition is satisfied, or after a timeout.

Working with S3 Buckets and Objects

Create a bucket:

aws s3api create-bucket \
  --bucket my-app-artifacts \
  --region us-east-1 \
  --profile production \
  --create-bucket-configuration LocationConstraint=us-east-1

• s3api is the low-level interface to S3, exposing all REST API operations.
• LocationConstraint is required for non-default regions (e.g., us-east-1).
• The CLI returns a JSON response, which can be parsed with --query.

Upload a file:

aws s3 cp ./build/index.html s3://my-app-artifacts/www/index.html \
  --profile staging \
  --acl public-read \
  --cache-control "max-age=3600"

• cp (copy) works recursively, with --recursive or --recursive and --exclude filters.
• --acl accepts values: private, public-read, public-read-write, authenticated-read, bucket-owner-read, bucket-owner-full-control.
• --cache-control sets the Cache-Control HTTP header on the object.

Synchronize a local directory:

aws s3 sync ./dist/ s3://my-app-artifacts/dist/ \
  --profile production \
  --delete \
  --exclude "*.log" \
  --include "*.js" \
  --include "*.css"

• sync compares local and remote paths and uploads only changed files.
• --delete deletes remote objects no longer present locally.
• --exclude and --include support glob patterns (*.js, **/*.min.js).

Managing CloudFormation Stacks

Create a stack:

aws cloudformation create-stack \
  --stack-name my-app-prod \
  --template-body file://templates/app.yaml \
  --parameters ParameterKey=Environment,ParameterValue=prod \
  --parameters ParameterKey=InstanceType,ParameterValue=m5.large \
  --profile production \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

• --template-body supports inline JSON, file paths, and URLs.
• --parameters accepts repeated key-value pairs; CAPABILITY_IAM enables IAM resource creation.
• CAPABILITY_NAMED_IAM allows the stack to create named IAM roles and policies.

Update a stack:

aws cloudformation update-stack \
  --stack-name my-app-prod \
  --template-body file://templates/app.yaml \
  --parameters ParameterKey=Environment,ParameterValue=prod \
  --parameters ParameterKey=InstanceType,ParameterValue=t3.large \
  --profile production \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM

• The CLI compares the new template with the current stack and identifies differences.
• Updates are applied incrementally, and changes are reported via --change-set-name.

Monitor stack updates:

aws cloudformation wait stack-update-complete \
  --stack-name my-app-prod \
  --profile production \
  --region us-east-1

• wait blocks until the stack reaches UPDATE_COMPLETE status.
• The command returns after all resources are created, updated, or deleted.

Using JSON and Querying Data

The CLI supports structured output via --output json, --output yaml, and --output table. The --query flag applies JMESPath expressions to filter and transform output.

Example: List EC2 instances and extract public IPs:

aws ec2 describe-instances \
  --filter "Name=tag:Environment,Values=prod" \
  --query 'Reservations[].Instances[].PublicIpAddress' \
  --output table

• --filter uses Name=value pairs; multiple filters are comma-separated.
• --query uses JMESPath syntax: Reservations[].Instances[].PublicIpAddress returns a list of IPs.
• Output formats:
• json: full JSON object
• yaml: YAML-formatted output
• table: tabular, aligned output with headers

Example: Query for a single instance with custom formatting:

aws ec2 describe-instances \
  --instance-ids i-1234567890abcdef0 \
  --query 'Reservations[0].Instances[0].[InstanceId, State.Name, PublicIpAddress]' \
  --output table

• Output:

  -----------------------------
  InstanceId      State.Name    PublicIpAddress
  --------------  ------------  -----------------
  i-1234567890abcdef0  running       52.1.1.1

Advanced Patterns and Common Pitfalls

Handling Pagination and Multiple Pages

AWS CLI automatically paginates responses when a service returns more results than fit in a single API call. The --page-size and --max-items flags control pagination.

Retrieve all EC2 instances:

aws ec2 describe-instances \
  --output json \
  --query 'Reservations[].Instances[].InstanceId' \
  --max-items 100

• --max-items limits the total number of items returned.
• --page-size sets the number of items per page (default: 100).
• The CLI fetches multiple pages automatically and combines them.

Error Handling and Debugging

Common error responses:

{
  "Code": "InvalidParameterValue",
  "Message": "The value 't3.xlarge' for parameter InstanceType is invalid.",
  "Status": 400,
  "RequestID": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
}

• InvalidParameterValue occurs when a parameter is missing, malformed, or out of range.
• ValidationError is returned when the request body is invalid.
• AccessDenied appears when credentials lack required permissions.

Debugging with --debug:

aws s3api get-object \
  --bucket my-bucket \
  --key path/to/file.txt \
  --output text \
  --debug

• --debug enables detailed logging of HTTP requests and responses.
• Logs include:
• Request URL, headers, body
• Response status, body, headers
• AWS request ID and retry attempts
• SDK-level diagnostics

Using AWS CLI with Shell Scripts

Example: Deploy script for a web app:

#!/bin/bash
set -euo pipefail

STACK_NAME="my-web-app-prod"
TEMPLATE_FILE="templates/web-app.yaml"
BUCKET_NAME="my-web-app-artifacts"


npm run build
aws s3 sync ./dist/ s3://${BUCKET_NAME}/dist/ --delete --profile production

# Deploy CloudFormation stack
aws cloudformation create-stack \
  --stack-name "${STACK_NAME}" \
  --template-body file://${TEMPLATE_FILE} \
  --parameters ParameterKey=AppBucket,ParameterValue=${BUCKET_NAME} \
  --capabilities CAPABILITY_IAM \
  --profile production \
  --region us-east-1 \
  --output json

aws cloudformation wait stack-create-complete \
  --stack-name "${STACK_NAME}" \
  --profile production \
  --region us-east-1

echo "Deployment complete: ${STACK_NAME}"

• set -euo pipefail ensures strict script execution:
• -e: exit on error
• -u: error on undefined variables
• -o pipefail: pipe fails if any command in the pipeline fails

Silent Failures and Configuration Traps

• Default region is not always us-east-1: If region is not set in ~/.aws/config, AWS_DEFAULT_REGION, or --region, the CLI uses the region of the first service call.
• --profile does not override AWS_PROFILE environment variable: If both are set, --profile takes precedence.
• --query does not work on top-level objects: For aws ec2 describe-instances, --query 'Instances[].InstanceId' returns a list, but --query 'Instances' returns a nested list of instances.
• --output is not applied to wait commands: aws ec2 wait instance-status-ok --output json returns JSON, but --query does not apply to the wait output unless --output is set explicitly.
• Role assumption fails silently: If role_arn is set but the role does not exist or the caller lacks sts:AssumeRole, the CLI logs the error but continues, using default credentials.

Best Practices

• Use --profile consistently across scripts and CI pipelines.
• Prefer s3api for low-level S3 operations and s3 for high-level file operations.
• Use --query with --output table for human-readable reports.
• Combine wait commands with --debug to validate pipeline correctness.
• Cache aws sts get-caller-identity in scripts to validate current context.

The AWS CLI is not just a command-line tool—it is the backbone of AWS automation. Mastery comes not from memorizing commands, but from understanding how profiles, pagination, error handling, and query resolution interact across services.

This page was rewritten on 14 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.