AWS CLI Operations

AWS CLI v2 Operations

Guidance for using the AWS Command Line Interface effectively and safely.

Current version: AWS CLI v2 is in the 2.33.x range. CLI v1 enters maintenance mode July 15, 2026 and reaches end of support July 15, 2027. All guidance here targets v2.

Pre-Flight: Always Verify Context

Before executing ANY AWS CLI command, verify identity and region:

aws sts get-caller-identity
aws configure get region

Never assume which account or region is active. Environment variables, profile defaults, and SSO sessions can all silently change the target.

Core Principles

1. Verify before mutating — Always get-caller-identity before write/delete operations
2. Dry-run first — Use --dry-run (EC2) or --dryrun (S3) before destructive actions
3. Query server-side — Use --query (JMESPath) and --filters to reduce response size
4. Disable pager in scripts — Set AWS_PAGER="" or --no-cli-pager; v2 enables pager by default which blocks scripts
5. Script with text output — Use --output text for pipeable, scriptable results
6. Pin profiles explicitly — Always pass --profile and --region in scripts; never rely on environment defaults
7. Paginate consciously — CLI v2 auto-paginates; use --no-paginate or --max-items when you need control
8. Use aws login or SSO — aws login (v2.32.0+) is the simplest browser-based auth; aws configure sso for org-managed Identity Center; IAM roles for machines; long-term keys as last resort

Essential Command Patterns

Resource Discovery

# List all EC2 instances with name, type, state as table
aws ec2 describe-instances \
  --query 'Reservations[].Instances[].{Name:Tags[?Key==`Name`].Value|[0],ID:InstanceId,Type:InstanceType,State:State.Name}' \
  --output table

# Find resources by tag across all services
aws resourcegroupstaggingapi get-resources \
  --tag-filters Key=Environment,Values=production

# List S3 buckets with creation dates
aws s3api list-buckets --query 'Buckets[].{Name:Name,Created:CreationDate}' --output table

Safe Mutation Pattern

# Step 1: Verify identity
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)
echo "Account: $ACCOUNT  Region: $REGION"

# Step 2: Dry-run the operation
aws ec2 run-instances --image-id ami-xxx --instance-type t3.micro \
  --region "$REGION" --dry-run

# Step 3: Execute with minimal scope
aws ec2 run-instances --image-id ami-xxx --instance-type t3.micro --count 1 \
  --region "$REGION" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=my-instance}]'

Credential Management

aws login                              # browser-based (v2.32.0+, simplest)
aws login --remote                     # headless/SSH
aws configure sso                      # org-managed Identity Center
aws sso login --profile my-profile     # refresh SSO session
aws sts assume-role --role-arn ARN --role-session-name s --query Credentials  # cross-account

aws login auto-refreshes every 15 min (up to 12h), caches at ~/.aws/login/cache. Requires SignInLocalDevelopmentAccess managed policy. Remove any ~/.aws/credentials entries that might override login creds.

For full credential chain resolution, SSO session sharing, [sso-session] config, assumed-role export patterns, and credential gotchas, see references/advanced-patterns.md#credential-chain-and-profiles.

S3 Operations

aws s3 sync ./local s3://bucket/prefix --dryrun   # always dry-run first
aws s3 sync ./local s3://bucket/prefix --delete    # mirror mode
aws s3 cp large.zip s3://bucket/ --expected-size BYTES  # large file upload
aws s3 sync . s3://bucket --exclude "*.log" --exclude ".git/*"

For CRT transfer client (2-6x throughput), transfer acceleration, multipart tuning, --no-overwrite (v2.32.0+), and --case-conflict (v2.33+), see references/advanced-patterns.md#s3-transfer-optimization.

Waiting for Resources

aws ec2 wait instance-running --instance-ids i-xxx
aws cloudformation wait stack-create-complete --stack-name my-stack
aws rds wait db-instance-available --db-instance-identifier mydb

Waiters timeout after ~10 min and return exit code 255. For advanced waiter patterns and chaining, see references/advanced-patterns.md#waiter-patterns.

Output and Filtering

--query (JMESPath) vs --filters

Best practice: Filter server-side with --filters, then shape output with --query:

aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" \
  --query 'Reservations[].Instances[].{ID:InstanceId,Type:InstanceType}'

For JMESPath gotchas, nested filtering, sort/limit, and pipe expressions, see references/advanced-patterns.md#jmespath-queries.

Output Format Selection

Script Safety Checklist

Verify before shipping:

• set -euo pipefail at script top
• --tag-specifications on every resource-creation call
• S3 versioning enabled on critical buckets before bulk operations
• Check --help for non-obvious required params on unfamiliar commands
• No --no-verify-ssl in production
• Sensitive output (keys, secrets) never piped to stdout unredacted
• No --force flags without understanding what they skip
• No create-access-key calls in automation scripts

Common Gotchas

• Pager blocks scripts: v2 enables less by default. Fix: export AWS_PAGER="" or --no-cli-pager.
• Pagination surprise: v2 auto-paginates; a describe-instances with 10K instances returns ALL of them. Use --max-items to cap.
• Text + query pagination trap: --output text runs --query per page, not the full dataset. Use json or yaml when --query must operate on complete results.
• Region mismatch: Resources are region-scoped. Global services (IAM, Route53, CloudFront) use us-east-1 implicitly.
• S3 sync compares size + timestamp, not content. Use --exact-timestamps for precision.
• Filter vs query naming: --filters uses API names (instance-state-name); --query uses response JSON names (State.Name).
• Waiter timeouts: ~10 min default, exit code 255 on timeout — crashes set -e scripts. Capture exit code explicitly.
• SSO token expiry: 1-8 hours typically. Run aws sso login to refresh. aws login auto-refreshes (15 min intervals, up to 12h).
• CloudFormation drift: describe-stacks shows template state, not actual. Use detect-stack-drift for truth.

For exit codes table, v1-to-v2 migration tool, and v2 behavioral changes, see references/advanced-patterns.md#exit-codes-v2.

Dangerous Commands Reference

Before running any destructive AWS CLI command, consult the safety reference for tiered risk commands (irreversible data loss, service disruption, cost explosion), safer alternatives, and pre-execution checklists: references/dangerous-commands.md.

Advanced Patterns Reference

For JMESPath queries, pagination control, waiter patterns, output formats, credential chain and SSO session config, S3 transfer optimization, multi-account/cross-region loops, CLI aliases, and scripting templates: references/advanced-patterns.md.

Service Patterns Reference

For VPC provisioning, Lambda deployment, DynamoDB operations, RDS management, CloudWatch observability, SSM Parameter Store, and Security Groups: references/service-patterns.md.