aws: Universal Command Line Interface for Amazon Web Services (AWS CLI v2)
aws [options] <command> <subcommand> [parameters]
Options you will use
--profile NAME- Use this named profile from ~/.aws/config and ~/.aws/credentials (also AWS_PROFILE). With --profile, AWS_ACCESS_KEY_ID in the environment is ignored.
--region REGION- The Region to send the request to (also AWS_REGION, AWS_DEFAULT_REGION, the profile's region). IAM is global; most services are regional.
--output FORMAT- json (default), text (tab separated, for shell loops), table, yaml, yaml-stream, off.
--query EXPR- A JMESPath expression applied by the CLI to the response, after pagination: Users[].UserName, Buckets[?starts_with(Name,
oncall)].Name. Quote it in single quotes. --no-paginate- Only the first page (the service's own page size), with the service's marker in the output.
--max-items N- Print at most N items and a NextToken to continue with --starting-token (paginated operations).
--page-size N- The size of each API page; the CLI still fetches every page. For calls that time out on big pages.
--debug- Log every step: the credential chain, the request, the response headers. Goes to stderr.
--no-cli-pager- Do not send the output to a pager (also AWS_PAGER="" or cli_pager = in the config).
--cli-error-format FORMAT- enhanced (default since 2.34: aws: [ERROR]: ...), json, yaml, text, table, legacy (the old "An error occurred ..." text).
--cli-binary-format FMT- base64 (default in v2: blob parameters are base64 text) or raw-in-base64-out (blobs given as raw text).
--cli-connect-timeout SECONDS- How long to wait for the connection (default 60; 0 = forever). A short one turns a missing network path into a quick "Connect timeout on endpoint URL".
--cli-read-timeout SECONDS- How long to wait for a response once connected (default 60; 0 = forever).
--endpoint-url URL- Send the request to another endpoint (LocalStack, a VPC endpoint, FIPS).
--no-sign-request- Send the request without credentials (anonymous): only works on public resources.
--generate-cli-skeleton- Print the JSON skeleton of the operation's parameters (fill it in, then --cli-input-json file://x.json).
--cli-input-json JSON- Reads arguments from the JSON string provided (file://path for a file). The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. This may not be specified along with --cli-input-yaml.
--cli-input-yaml YAML- Reads arguments from the YAML string provided, in the format --generate-cli-skeleton yaml-input prints. This may not be specified along with --cli-input-json.
Examples
$ aws sts get-caller-identitywho am I: account, user or role ARN
$ aws configure listwhich credentials and region the CLI would use, and from where
$ aws iam list-users --query 'Users[].UserName' --output textone line of names, for a shell loop
$ aws s3 ls s3://bucket/prefix/ --recursive --human-readable --summarizewhat is in a bucket, how big
$ aws sts assume-role --role-arn ARN --role-session-name metemporary credentials for a role
$ aws rds reboot-db-instance --db-instance-identifier shop --force-failoverfail a Multi-AZ instance over to its standby
$ aws cloudfront create-invalidation --distribution-id E2QWRUHAPOMQZL --paths '/*'drop everything from the edge caches
Gotchas
aws sts get-caller-identityis whoami: it needs no permission and works even under an explicit deny.- AccessDenied messages name the policy type that denied: "because no identity-based policy allows the X action" (nothing allows it), "with an explicit deny in a service control policy: arn:..." (a Deny wins over every Allow), "because no permissions boundary allows", "because no resource-based policy allows" (a KMS key policy).
- Ubuntu 26.04's
apt install awscligives 2.31.35 (Debian's packaging, behind upstream). The official installer (awscli-exe-linux-aarch64.zip) gives the current release under /usr/local/aws-cli. - Credentials in environment variables beat AWS_PROFILE. An old
export AWS_ACCESS_KEY_ID=...in ~/.bashrc silently overrides every profile -aws configure listshows where each value comes from. - Output is sent to a pager (less) on a terminal. Scripts and CI: AWS_PAGER="" or --no-cli-pager.
- RDS endpoints are DNS names (a CNAME, TTL 5 s): after a Multi-AZ failover the name points at the new primary; clients that cache the address keep talking to the old one.
- DynamoDB items are DynamoDB JSON ({"n": {"N": "42"}} - numbers as strings); reserved words (status, name, data, total ...) need --expression-attribute-names.
- CloudFront is global: its certificates come from ACM in us-east-1, and a CLOUDFRONT-scope web ACL is created with --region us-east-1.
- VPC peering is not transitive; a transit gateway is.
- SQS: a received message is hidden for the visibility timeout, not removed - delete it with the ReceiptHandle of the LATEST receive or it comes back (ApproximateReceiveCount + 1); after maxReceiveCount it goes to the dead-letter queue. The queue URL, not the name, is the parameter.
- SNS -> SQS / Lambda needs the DESTINATION to allow it: a queue policy (or a Lambda add-permission) for sns.amazonaws.com with aws:SourceArn = the topic. Without it nothing arrives and nothing errors (NumberOfNotificationsFailed).
- Lambda invoke in CLI v2: --payload is a blob, base64 by default - add --cli-binary-format raw-in-base64-out (or set cli_binary_format in ~/.aws/config) to pass JSON. A function error still returns StatusCode 200 with FunctionError: Unhandled; the error JSON is in the output file.
- Lambda logs go to /aws/lambda/<name> only if the execution role may write them (AWSLambdaBasicExecutionRole). REPORT lines: Duration, Billed Duration (the INIT phase is billed too), Max Memory Used, Init Duration on a cold start, Status: timeout.
- An SQS event source mapping needs the queue visibility timeout >= the function timeout (AWS recommends 6x) and ReceiveMessage / DeleteMessage / GetQueueAttributes on the role. Return {"batchItemFailures": [{"itemIdentifier": messageId}]} with ReportBatchItemFailures to retry only the failed messages.
- API Gateway REST: an unknown path or method is 403 {"message":"Missing Authentication Token"}; a Lambda error or a malformed proxy response is 502; no lambda:InvokeFunction permission for apigateway.amazonaws.com is 500. Changes reach a stage only with create-deployment.
- ECS on Fargate: the EXECUTION role pulls the image, writes awslogs and reads secrets; the TASK role is what the app calls AWS with. A task in a private subnet needs a NAT gateway or the ecr.api + ecr.dkr + s3 (+ logs) endpoints; a public subnet needs assignPublicIp=ENABLED - else ResourceInitializationError / CannotPullContainerError.
- Step Functions: Retry is tried before Catch; ErrorEquals matches the Lambda errorType (or States.ALL, States.TaskFailed, States.Timeout). describe-execution shows error + cause; get-execution-history shows every attempt.
- Kinesis: the partition key picks the shard (MD5 into the hash key ranges); order is kept per shard only. A shard takes 1 MiB or 1,000 records per second in; iterators expire after 5 minutes.
Taught in
- 34.1 AWS for Azure people: accounts, regions, ARNs and the API
- 34.2 The AWS CLI v2: install, configure, profiles and the credential chain
- 34.5 Output, --query, pagination and reading errors
- 34.8 IAM: principals, groups, policies and the policy language
- 34.10 Policy evaluation: how AWS decides, and reading AccessDenied
- 34.14 Roles and STS: trust policies, assume-role and temporary credentials
- 34.18 Access keys: rotation, leaks and CloudTrail
- 34.22 S3: buckets, keys, prefixes and the s3 commands
On the blog
Try aws in a real terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.