Cloud
AWS CLI — auth, context, and everyday operations
Everyday aws CLI reference: authenticate (SSO/profiles), confirm WHO you are and WHICH account/region is active, read and describe resources, tail logs, and run the handful of scoped create/deploy ops people actually touch. Confirm context with sts get-caller-identity before any write.
Quick reference — reach for these first
aws sts get-caller-identityPrints Account, Arn, UserId for the currently resolved credentials — run before any changeaws sso login --profile PROFILERenews the short-lived IAM Identity Center token for that profileexport AWS_PROFILE=PROFILE AWS_REGION=REGIONSets profile + region for this shell; overrides config defaultsaws s3 lsLists buckets — fast check that creds and region actually workaws logs tail GROUP --follow --since 10mStreams a CloudWatch Logs group in real timeAWS CLI credential & context resolution (first match wins)
Text equivalent: A vertical stack of four credential sources the AWS CLI checks in order, top to bottom: 1 CLI flags such as --profile and --region; 2 environment variables AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_REGION; 3 shared files ~/.aws/config and credentials plus the SSO cache; 4 EC2/container instance role via IMDS. An arrow down the left is labeled 'first match wins'. A box on the right says: confirm the winner with aws sts get-caller-identity, which returns Account, Arn, and UserId. A note at the bottom warns that if no region is set in sources 1 to 3 and you are not on EC2, the CLI errors 'You must specify a region'.
Common tasks
Task · Command · What to check
| Task | Command | What to check |
|---|---|---|
| Configure an SSO (Identity Center) profile | aws configure sso | ~/.aws/config gains [profile PROFILE] with an sso_session block |
| Log in / refresh the SSO token | aws sso login --profile PROFILE | "Successfully logged into Start URL"; sts call below then succeeds |
| Confirm identity + account (do this first) | aws sts get-caller-identity --profile PROFILE | Account equals the expected ACCOUNT_ID and Arn is the role you meant |
| Set default profile + region for the shell | export AWS_PROFILE=PROFILE AWS_REGION=REGION | aws configure list shows profile/region sourced from 'env' |
| List configured profiles | aws configure list-profiles | The profile you expect appears in the output |
| Persist a region on a profile | aws configure set region REGION --profile PROFILE | aws configure get region --profile PROFILE returns REGION |
| List S3 buckets / a bucket's objects | aws s3 ls # aws s3 ls s3://BUCKET/ | Expected buckets/keys returned; no AccessDenied |
| Describe EC2 instances in the region | aws ec2 describe-instances --query 'Reservations[].Instances[].[InstanceId,State.Name]' --output table | Instances for REGION listed with state |
| Tail a CloudWatch Logs group | aws logs tail GROUP --follow --since 15m | Live log events stream to the terminal |
| List ECS services in a cluster | aws ecs list-services --cluster CLUSTER | Service ARNs returned for CLUSTER |
| Deploy an ECS service [LABEL: billable / prod] | aws ecs update-service --cluster CLUSTER --service SERVICE --force-new-deployment | describe-services shows a new deployment PRIMARY rolling out |
| Wire kubectl to an EKS cluster | aws eks update-kubeconfig --name CLUSTER --region REGION | kubectl get ns succeeds against the right cluster |
| Inspect IAM roles/user for the principal | aws iam list-roles --query 'Roles[].RoleName' # aws iam get-user | Expected roles listed (no AccessDenied) |
| Stop one instance, scoped [LABEL: destructive] | aws ec2 stop-instances --instance-ids INSTANCE_ID | CurrentState transitions to 'stopping' for only that INSTANCE_ID |
From zero: authenticate, CONFIRM context, one safe read, one scoped write, verify
auth → confirm → read → scoped write → verify
aws sso login --profile PROFILE
# Successfully logged into Start URL: https://d-xxxx.awsapps.com/startexport AWS_PROFILE=PROFILE AWS_REGION=REGION
aws sts get-caller-identity
# {
# "Account": "ACCOUNT_ID",
# "Arn": "arn:aws:sts::ACCOUNT_ID:assumed-role/AWSReservedSSO_Admin/you"
# }aws s3 ls
# 2026-01-02 09:14:31 my-app-logsaws ec2 create-tags --resources INSTANCE_ID --tags Key=Owner,Value=me
aws ec2 describe-instances --instance-ids INSTANCE_ID --query 'Reservations[].Instances[].Tags'
# [[{"Key":"Owner","Value":"me"}]]Troubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| AccessDenied / not authorized to perform | aws sts get-caller-identity | Which principal (Arn) the CLI is actually using | Confirm the Arn's IAM policy grants the action, or switch --profile/role; re-run |
| ExpiredToken / the security token has expired | aws sts get-caller-identity | Credentials expired vs. genuinely wrong principal | aws sso login --profile PROFILE (or rotate static keys), then retry |
| Wrong account/project — expected resources are missing | aws sts get-caller-identity; echo $AWS_PROFILE | Which account/profile the CLI is pointed at right now | Set AWS_PROFILE or --profile to the intended account before acting |
| You must specify a region | aws configure get region; echo $AWS_REGION | No region resolved from flags, env, or profile | export AWS_REGION=REGION, pass --region REGION, or configure set region |
| Throttling / Rate exceeded / TooManyRequests | Read the error code in the response | Server-side throttle rather than a client/auth error | Let built-in retries run, or set AWS_RETRY_MODE=adaptive and AWS_MAX_ATTEMPTS; back off / narrow the query |
| Could not connect to the endpoint URL | Verify REGION and that the service exists there | Bad region/endpoint vs. network or proxy block | Correct --region, or check VPC egress / HTTP(S)_PROXY settings |
| Unable to locate credentials | aws configure list | Nothing resolved anywhere in the credential chain | aws configure sso (or configure) to set up PROFILE, then sso login |
References
- AWS CLI Command Referencedocs.aws.amazon.com
- Configure the AWS CLI with IAM Identity Center (SSO)docs.aws.amazon.com
- Configuration & credential precedencedocs.aws.amazon.com
- sts get-caller-identitydocs.aws.amazon.com
- Configure AWS CLI retriesdocs.aws.amazon.com
AWS CLI v2 on macOS/Linux with IAM Identity Center (SSO) profiles; adjust for static IAM keys or CLI v1.