# Using the AWS CLI
This section provides a comprehensive overview of the general use, common features, and options available in the AWS Command Line Interface (AWS CLI), going beyond the details covered in the Configuration [Using endpoints in the AWS CLI](cli-configure-endpoints.md) section.
This guide delves into the fundamental aspects of writing AWS CLI commands, including their basic structure, formatting, and filtering capabilities. By understanding these core elements, you'll be able to construct commands that precisely target the resources and actions you require, without the need to navigate complex web-based consoles.
Additionally, this highlights the help content and documentation available for the AWS CLI. From the built-in command line help to the comprehensive [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/), you'll have access to information to assist you in exploring the features and capabilities of the AWS CLI.
For AWS service specific examples and use cases, see [Examples for the AWS CLI](cli-chap-code-examples.md) or the [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/). These provide command specific information and demonstrate examples on how to leverage the AWS CLI for various AWS services.
**Note**
By default, the AWS CLI sends requests to AWS services by using HTTPS on TCP port 443. To ensure successful use of the AWS CLI, you must be able to make outbound connections on this port.
**Topics**
+ [Accessing help and resources for the AWS CLI](cli-usage-help.md)
+ [Command structure in the AWS CLI](cli-usage-commandstructure.md)
+ [Specifying parameter values in the AWS CLI](cli-usage-parameters.md)
+ [Enabling and using command prompts in the AWS CLI](cli-usage-parameters-prompting.md)
+ [Controlling command output in the AWS CLI](cli-usage-output.md)
+ [Command line return codes in the AWS CLI](cli-usage-returncodes.md)
+ [Using custom wizards to run interactive commands in the AWS CLI](cli-usage-wizard.md)
+ [Creating and using aliases in the AWS CLI](cli-usage-alias.md)
+ [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md)
# Accessing help and resources for the AWS CLI
This topic describes how to access help content for the AWS Command Line Interface (AWS CLI).
**Topics**
+ [The built-in AWS CLI help command](#cli-usage-help-command)
+ [AWS CLI reference guide](#cli-reference)
+ [API documentation](#api-reference)
+ [Troubleshooting errors](#help-tshoot)
+ [Additional help](#help-additional)
## The built-in AWS CLI help command
You can get help with any command when using the AWS Command Line Interface (AWS CLI). To do so, simply type `help` at the end of a command name.
For example, the following command displays help for the general AWS CLI options and the available top-level commands.
```
$ aws help
```
The following command displays the available Amazon Elastic Compute Cloud (Amazon EC2) specific commands.
```
$ aws ec2 help
```
The following example displays detailed help for the Amazon EC2 `DescribeInstances` operation. The help includes descriptions of its input parameters, available filters, and what is included as output. It also includes examples showing how to type common variations of the command.
```
$ aws ec2 describe-instances help
```
As of version `2.31.0` The display for the `help` command is configured by the `cli_help_output` setting, and has the following values:
+ **(default)** `terminal` ‐ Open the man page in the terminal.
+ `browser` ‐ Open the man page as a local HTML file in your default browser. A notice is printed to your terminal when your default browser is being opened, and an error message if the AWS CLI cannot open your browser.
+ `url` ‐ Print the URL to the online AWS CLI Reference Guide for the version of the AWS CLI you have installed. Settings for client-side paging, such as the `AWS_PAGER` environment variable, is respected.
The help content for each command is divided into six sections:
Name
The name of the command.
```
NAME
describe-instances -
```
Description
A description of the API operation that the command invokes.
```
DESCRIPTION
Describes one or more of your instances.
If you specify one or more instance IDs, Amazon EC2 returns information
for those instances. If you do not specify instance IDs, Amazon EC2
returns information for all relevant instances. If you specify an
instance ID that is not valid, an error is returned. If you specify an
instance that you do not own, it is not included in the returned
results.
...
```
Synopsis
The basic syntax for using the command and its options. If an option is shown in square brackets, it's optional, has a default value, or has an alternative option that you can use.
```
SYNOPSIS
describe-instances
[--dry-run | --no-dry-run]
[--instance-ids ]
[--filters ]
[--cli-input-json ]
[--starting-token ]
[--page-size ]
[--max-items ]
[--generate-cli-skeleton]
```
For example, `describe-instances` has a default behavior that describes ***all*** instances in the current account and AWS Region. You can optionally specify a list of `instance-ids` to describe one or more instances; `dry-run` is an optional Boolean flag that doesn't take a value. To use a Boolean flag, specify either shown value, in this case `--dry-run` or `--no-dry-run`. Likewise, `--generate-cli-skeleton` doesn't take a value. If there are conditions on an option's use, they are described in the `OPTIONS` section, or shown in the examples.
Options
A description of each of the options shown in the synopsis.
```
OPTIONS
--dry-run | --no-dry-run (boolean)
Checks whether you have the required permissions for the action,
without actually making the request, and provides an error response.
If you have the required permissions, the error response is DryRun-
Operation . Otherwise, it is UnauthorizedOperation .
--instance-ids (list)
One or more instance IDs.
Default: Describes all your instances.
...
```
Examples
Examples showing the usage of the command and its options. If no example is available for a command or use case that you need, request one using the feedback link on this page, or in the AWS CLI command reference on the help page for the command.
```
EXAMPLES
To describe an Amazon EC2 instance
Command:
aws ec2 describe-instances --instance-ids i-5203422c
To describe all instances with the instance type m1.small
Command:
aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small"
To describe all instances with an Owner tag
Command:
aws ec2 describe-instances --filters "Name=tag-key,Values=Owner"
...
```
Output
Descriptions of each of the fields and data types included in the response from AWS.
For `describe-instances`, the output is a list of reservation objects, each of which contains several fields and objects that contain information about the instances associated with it. This information comes from the [API documentation for the reservation data type](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Reservation.html) used by Amazon EC2.
```
OUTPUT
Reservations -> (list)
One or more reservations.
(structure)
Describes a reservation.
ReservationId -> (string)
The ID of the reservation.
OwnerId -> (string)
The ID of the AWS account that owns the reservation.
RequesterId -> (string)
The ID of the requester that launched the instances on your
behalf (for example, AWS Management Console or Auto Scaling).
Groups -> (list)
One or more security groups.
(structure)
Describes a security group.
GroupName -> (string)
The name of the security group.
GroupId -> (string)
The ID of the security group.
Instances -> (list)
One or more instances.
(structure)
Describes an instance.
InstanceId -> (string)
The ID of the instance.
ImageId -> (string)
The ID of the AMI used to launch the instance.
State -> (structure)
The current state of the instance.
Code -> (integer)
The low byte represents the state. The high byte
is an opaque internal value and should be ignored.
...
```
When the AWS CLI renders the output into JSON, it becomes an array of reservation objects, similar to the following example.
```
{
"Reservations": [
{
"OwnerId": "012345678901",
"ReservationId": "r-4c58f8a0",
"Groups": [],
"RequesterId": "012345678901",
"Instances": [
{
"Monitoring": {
"State": "disabled"
},
"PublicDnsName": "ec2-52-74-16-12.us-west-2.compute.amazonaws.com",
"State": {
"Code": 16,
"Name": "running"
},
...
```
Each reservation object contains fields describing the reservation and an array of instance objects, each with its own fields (for example, `PublicDnsName`) and objects (for example, `State`) that describe it.
**Windows users**
You can *pipe* (\$1) the output of the help command to the `more` command to view the help file one page at a time. Press the space bar or **PgDn** to view more of the document, and **q** to quit.
```
C:\> aws ec2 describe-instances help | more
```
## AWS CLI reference guide
The help files contain links that cannot be viewed or navigated to from the command line. You can view and interact with these links by using the online [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/index.html). The reference also contains the help content for all AWS CLI commands. The descriptions are presented for easy navigation and viewing on mobile, tablet, or desktop screens.
## API documentation
All commands in the AWS CLI correspond to requests made to an AWS service's public API. Each service with a public API has an API reference that can be found on the service's home page on the [AWS Documentation website](https://docs.aws.amazon.com/). The content for an API reference varies based on how the API is constructed and which protocol is used. Typically, an API reference contains detailed information about the operations supported by the API, the data sent to and from the service, and any error conditions that the service can report.
**API Documentation Sections**
+ **Actions** – Detailed information on each operation and its parameters (including constraints on length or content, and default values). It lists the errors that can occur for this operation. Each operation corresponds to a subcommand in the AWS CLI.
+ **Data Types** – Detailed information about structures that a command might require as a parameter, or return in response to a request.
+ **Common Parameters** – Detailed information about the parameters that are shared by all of action for the service.
+ **Common Errors** – Detailed information about errors that can be returned by any of the service's operations.
The name and availability of each section can vary, depending on the service.
**Service-specific CLIs**
Some services have a separate CLI that dates from before a single AWS CLI was created to work with all services. These service-specific CLIs have separate documentation that is linked from the service's documentation page. Documentation for service-specific CLIs do not apply to the AWS CLI.
## Troubleshooting errors
For help diagnosing and fixing AWS CLI errors, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md).
## Additional help
For additional help with your AWS CLI issues, visit the [AWS CLI community](https://github.com/aws/aws-cli/issues) on *GitHub*.
# Command structure in the AWS CLI
This topic covers how AWS Command Line Interface (AWS CLI) command is structured, and how to use wait commands.
**Topics**
+ [Command structure](#cli-usage-commandstructure-structure.title)
+ [Wait commands](#cli-usage-commandstructure-wait)
## Command structure
The AWS CLI uses a multipart structure on the command line that must be specified in this order:
1. The base call to the `aws` program.
1. The top-level *command*, which typically corresponds to an AWS service supported by the AWS CLI.
1. The *subcommand* that specifies which operation to perform.
1. General AWS CLI options or parameters required by the operation. You can specify these in any order as long as they follow the first three parts. If an exclusive parameter is specified multiple times, only the *last value* applies.
```
$ aws [options and parameters]
```
Parameters can take various types of input values, such as numbers, strings, lists, maps, and JSON structures. What is supported is dependent upon the command and subcommand you specify.
### Examples
**Amazon S3**
The following example lists all of your Amazon S3 buckets.
```
$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2
```
For more information on the Amazon S3 commands, see [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) in the *AWS CLI Command Reference*.
**AWS CloudFormation**
The following [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html)command example changes the cloudformation stack name to *my-change-set*.
```
$ aws cloudformation create-change-set --stack-name my-stack --change-set-name my-change-set
```
For more information on the AWS CloudFormation commands, see [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html) in the *AWS CLI Command Reference*.
## Wait commands
Some AWS services have `wait` commands available. Any command that uses `aws wait` usually waits until a command is complete before it moves on to the next step. This is especially useful for multipart commands or scripting, as you can use a wait command to prevent moving to subsequent steps if the wait command fails.
The AWS CLI uses a multipart structure on the command line for the `wait` command that must be specified in this order:
1. The base call to the `aws` program.
1. The top-level *command*, which typically corresponds to an AWS service supported by the AWS CLI.
1. The `wait` command.
1. The *subcommand* that specifies which operation to perform.
1. General CLI options or parameters required by the operation. You can specify these in any order as long as they follow the first three parts. If an exclusive parameter is specified multiple times, only the *last value* applies.
```
$ aws wait [options and parameters]
```
Parameters can take various types of input values, such as numbers, strings, lists, maps, and JSON structures. What is supported is dependent upon the command and subcommand you specify.
**Note**
Not every AWS service supports `wait` commands. See the [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/index.html) to see if your service supports `wait` commands.
### Examples
**AWS CloudFormation**
The following [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) command examples pauses and resumes only after it can confirm that the *my-change-set* change set in the *my-stack* stack is ready to run.
```
$ aws cloudformation wait change-set-create-complete --stack-name my-stack --change-set-name my-change-set
```
For more information on the AWS CloudFormation `wait` commands, see [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html) in the *AWS CLI Command Reference*.
**AWS CodeDeploy**
The following [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) command examples pauses until the *d-A1B2C3111* deployment completes successfully.
```
$ aws deploy wait deployment-successful --deployment-id d-A1B2C3111
```
For more information on the AWS CodeDeploy `wait` commands, see [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html) in the *AWS CLI Command Reference*.
# Specifying parameter values in the AWS CLI
Many parameters used in the AWS Command Line Interface (AWS CLI) are simple string or numeric values, such as the key-pair name `my-key-pair` in the following `aws ec2 create-key-pair` command example.
```
$ aws ec2 create-key-pair --key-name my-key-pair
```
Formatting for command can vary between terminals. For example, most terminals are case sensitive but Powershell is case insensitive. This means the two following command examples would yield different results for case sensitive terminals as they view `MyFile*.txt` and `myfile*.txt` as **different** parameters.
However, PowerShell would process these requests as the same as it sees `MyFile*.txt` and `myfile*.txt` as the **same** parameters. The following command example demonstrates these paramaters using the `aws s3 cp` command:
```
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "MyFile*.txt"
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "myfile*.txt"
```
For more information on PowerShell's case insensitivy, see [about\$1Case-Sensitivity](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity) in the *PowerShell documentation*.
Sometimes you need to use quotation marks or literals around strings that include special or space characters. The rules around this formatting can also vary between terminals. For more information about using quotation marks around complex parameters, see [Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md).
These topics cover the most common terminal formatting rules. If you are having issues with your terminal recognizing your parameter values, be sure to review the topics in this section and also to check your terminal's documentation for their specific syntax rules.
**Topics**
+ [Common parameter types in the AWS CLI](cli-usage-parameters-types.md)
+ [Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md)
+ [Loading a parameter from a file in the AWS CLI](cli-usage-parameters-file.md)
+ [AWS CLI skeletons and input files in the AWS CLI](cli-usage-skeleton.md)
+ [Using shorthand syntax in the AWS CLI](cli-usage-shorthand.md)
# Common parameter types in the AWS CLI
This section describes some of the common parameter types and the typical required format.
If you are having trouble formatting a parameter for a specific command, check the help by entering **help** after the command name. The help for each subcommand includes an option's name and description. The option's parameter type is listed in parentheses. For more information on viewing help, see [Accessing help and resources for the AWS CLI](cli-usage-help.md).
**Topics**
+ [String](#parameter-type-string)
+ [Timestamp](#parameter-type-timestamp)
+ [List](#parameter-type-list)
+ [Boolean](#parameter-type-boolean)
+ [Integer](#parameter-type-integer)
+ [Binary / blob (binary large object) and streaming blob](#parameter-type-blobs)
+ [Map](#parameter-type-map)
+ [Document](#parameter-type-document)
## String
String parameters can contain alphanumeric characters, symbols, and white spaces from the [ASCII](https://wikipedia.org/wiki/ASCII) character set. Strings that contain white spaces must be surrounded by quotation marks. We recommend that you don't use symbols or white spaces other than the standard space character and to observe your terminal's [quoting rules](cli-usage-parameters-quoting-strings.md) to prevent unexpected results.
Some string parameters can accept binary data from a file. See [Binary files](cli-usage-parameters-file.md#cli-usage-parameters-file-binary) for an example.
## Timestamp
Timestamps are formatted according to the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. These are often referred to as "`DateTime`" or "`Date`" parameters.
```
$ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z
```
Acceptable formats include:
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (UTC)*, for example, 2014-10-01T20:30:00.000Z
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (with offset)*, for example, 2014-10-01T12:30:00.000-08:00
+ *YYYY*-*MM*-*DD*, for example, 2014-10-01
+ Unix time in seconds, for example, 1412195400. This is sometimes referred to as [Unix Epoch time](https://wikipedia.org/wiki/Unix_time) and represents the number of seconds since midnight, January 1, 1970 UTC.
By default, the AWS CLI version 2 translates all ***response*** DateTime values to ISO 8601 format.
You can set the timestamp format by using the `cli\$1timestamp\$1format` file setting.
## List
One or more strings separated by spaces. If any of the string items contain a space, you must put quotation marks around that item. Observe your terminal's [quoting rules](cli-usage-parameters-quoting-strings.md) to prevent unexpected results.
```
$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium
```
## Boolean
Binary flag that turns an option on or off. For example, `ec2 describe-spot-price-history` has a Boolean `--dry-run` parameter that, when specified, validates the query with the service without actually running the query.
```
$ aws ec2 describe-spot-price-history --dry-run
```
The output indicates whether the command was well formed. This command also includes a `--no-dry-run` version of the parameter that you can use to explicitly indicate that the command should be run normally. Including it isn't necessary because this is the default behavior.
## Integer
An unsigned, whole number.
```
$ aws ec2 describe-spot-price-history --max-items 5
```
## Binary / blob (binary large object) and streaming blob
In the AWS CLI, you can pass a binary value as a string directly on the command line. There are two types of blobs:
+ [Blob](#parameter-type-blob)
+ [Streaming blob](#parameter-type-streaming-blob)
### Blob
To pass a value to a parameter with type `blob`, you must specify a path to a local file that contains the binary data using the `fileb://` prefix. Files referenced using the `fileb://` prefix are always treated as raw unencoded binary. The specified path is interpreted as being relative to the current working directory. For example, the `--plaintext` parameter for `aws kms encrypt` is a blob.
```
$ aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
**Note**
For backwards compatibility, you can use the `file://` prefix. There are two formats used based on the file setting `cli\$1binary\$1format` or `--cli-binary-format` command line option:
Default for the AWS CLI version 2. If the setting's value is `base64`, files referenced using the `file://` prefix are treated as base64-encoded text.
Default for the AWS CLI version 1. If the setting's value is `raw-in-base64-out`, files referenced using the `file://` prefix is read as text and then the AWS CLI attempts to encode it to binary.
For more information, see the file setting `cli\$1binary\$1format` or `--cli-binary-format` command line option.
### Streaming blob
Streaming blobs such as `aws cloudsearchdomain upload-documents` do not use prefixes. Instead, streaming blob parameters are formatted using the direct file path. The following example uses the direct file path `document-batch.json` for the `aws cloudsearchdomain upload-documents` command:
```
$ aws cloudsearchdomain upload-documents \
--endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \
--content-type application/json \
--documents document-batch.json
```
## Map
A set of key-value pairs specified in JSON or by using the CLI's [shorthand syntax](cli-usage-shorthand.md). The following JSON example reads an item from an Amazon DynamoDB table named *my-table* with a map parameter, `--key`. The parameter specifies the primary key named *id* with a number value of *1* in a nested JSON structure.
For more advanced JSON usage in a command line, consider using a command line JSON processor, like `jq`, to create JSON strings. For more information on `jq`, see the [jq repository](http://stedolan.github.io/jq/) on *GitHub*.
```
$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}'
{
"Item": {
"name": {
"S": "John"
},
"id": {
"N": "1"
}
}
}
```
## Document
**Note**
[Shorthand syntax](cli-usage-shorthand.md) is not compatible with document types.
Document types are used to send data without needing to embed JSON inside strings. The document type enables services to provide arbitrary schemas for you to use more flexible data types.
This allows for sending JSON data without needing to escape values. For example, instead of using the following escaped JSON input:
```
{"document": "{\"key\":true}"}
```
You can use the following document type:
```
{"document": {"key": true}}
```
### Valid values for document types
Due to the flexible nature of document types, there are multiple valid value types. Valid values include the following:
**String**
```
--option '"value"'
```
**Number**
```
--option 123
--option 123.456
```
**Boolean**
```
--option true
```
**Null**
```
--option null
```
**Array**
```
--option '["value1", "value2", "value3"]'
--option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]'
```
**Object**
```
--option '{"key": "value"}'
--option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}'
```
# Using quotation marks and literals with strings in the AWS CLI
There are primarily two ways single and double quotes are used in the AWS CLI.
+ [Using quotation marks around strings that contain white spaces](#cli-usage-parameters-quoting-strings-around)
+ [Using quotation marks inside strings](#cli-usage-parameters-quoting-strings-containing)
## Using quotation marks around strings that contain white spaces
Parameter names and their values are separated by spaces on the command line. If a string value contains an embedded space, then you must surround the entire string with quotation marks to prevent the AWS CLI from misinterpreting the space as a divider between the value and the next parameter name. Which type of quotation mark you use depends on the operating system you are running the AWS CLI on.
------
#### [ Linux and macOS ]
Use single quotation marks `' '`
```
$ aws ec2 create-key-pair --key-name 'my key pair'
```
For more information on using quotes, see the user documentation for your preferred shell.
------
#### [ PowerShell ]
**Single quotations (recommended)**
Single quotation marks `' '` are called `verbatim` strings. The string is passed to the command exactly as you type it, which means PowerShell variables will not pass through.
```
PS C:\> aws ec2 create-key-pair --key-name 'my key pair'
```
**Double quotations**
Double quotation marks `" "` are called `expandable` string. Variables can be passed in expandable strings.
```
PS C:\> aws ec2 create-key-pair --key-name "my key pair"
```
For more information on using quotes, see [About Quoting Rules](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) in the *Microsoft PowerShell Docs*.
------
#### [ Windows command prompt ]
Use double quotation marks `" "` .
```
C:\> aws ec2 create-key-pair --key-name "my key pair"
```
------
Optionally, you can separate the parameter name from the value with an equals sign `=` instead of a space. This is typically necessary only if the value of the parameter starts with a hyphen.
```
$ aws ec2 delete-key-pair --key-name=-mykey
```
## Using quotation marks inside strings
Strings might contain quotation marks, and your shell might require escaping quotations for them to work properly. One of the common parameter value types is a JSON string. This is complex since it includes spaces and double quotation marks `" "` around each element name and value in the JSON structure. The way you enter JSON-formatted parameters on the command line differs depending on your operating system.
For more advanced JSON usage in the command line, consider using a command line JSON processor, like `jq`, to create JSON strings. For more information on `jq`, see the [jq repository](http://stedolan.github.io/jq/) on *GitHub*.
------
#### [ Linux and macOS ]
For Linux and macOS to interpret strings literally use single quotation marks `' '` to enclose the JSON data structure, as in the following example. You do not need to escape double quotation marks embedded in the JSON string, as they are being treated literally. Since the JSON is enclosed in single quotation marks, any single quotation marks in the string will need to be escaped, this is usually accomplished using a backslash before the single quote `\'`.
```
$ aws ec2 run-instances \
--image-id ami-12345678 \
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
For more information on using quotes, see the user documentation for your preferred shell.
------
#### [ PowerShell ]
Use single quotation marks `' '` or double quotation marks `" "`.
**Single quotations (recommended)**
Single quotation marks `' '` are called `verbatim` strings. The string is passed to the command exactly as you type it, which means PowerShell variables will not pass through.
Since JSON data structures include double quotes, we suggest **single** quotation marks `' '` to enclose it. If you use **single** quotation marks, you do not need to escape **double** quotation marks embedded in the JSON string. However, you need to escape each **single** quotation mark with a backtick ``` within the JSON structure.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
**Double quotations**
Double quotation marks `" "` are called `expandable` strings. Variables can be passed in expandable strings.
If you use **double** quotation marks, you do not need to escape **single** quotation marks embedded in the JSON string. However, you need to escape each **double** quotation mark with a backtick ``` within the JSON structure, as with the following example.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`"DeviceName`":`"/dev/sdb`",`"Ebs`":{`"VolumeSize`":20,`"DeleteOnTermination`":false,`"VolumeType`":`"standard`"}}]"
```
For more information on using quotes, see [About Quoting Rules](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) in the *Microsoft PowerShell Docs*.
**Warning**
Before PowerShell sends a command to the AWS CLI, it determines if your command is interpreted using typical PowerShell or `CommandLineToArgvW` quoting rules. When PowerShell processes using `CommandLineToArgvW`, you must escape characters with a backslash `\`.
For more information on `CommandLineToArgvW` in PowerShell, see [What's up with the strange treatment of quotation marks and backslashes by CommandLineToArgvW](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833) in the *Microsoft DevBlogs*, [Everyone quotes command line arguments the wrong way](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way) in the *Microsoft Docs Blog*, and [CommandLineToArgvW function](https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw#remarks) in the *Microsoft Docs*.
**Single quotations**
Single quotation marks `' '` are called `verbatim` strings. The string is passed to the command exactly as you type it, which means PowerShell variables will not pass through. Escape characters with a backslash `\`.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]'
```
**Double quotations**
Double quotation marks `" "` are called `expandable` strings. Variables can be passed in `expandable` strings. For double quoted strings you have to escape twice using *`\$1* for each quote instead of only using a backtick. The backtick escapes the backslash, and then the backslash is used as an escape character for the `CommandLineToArgvW` process.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]"
```
**Blobs (recommended)**
To bypass PowerShell quoting rules for JSON data input, use Blobs to pass your JSON data directly to the AWS CLI. For more information on Blobs, see [Blob](cli-usage-parameters-types.md#parameter-type-blob).
------
#### [ Windows command prompt ]
The Windows command prompt requires double quotation marks `" "` to enclose the JSON data structure. Also, to prevent the command processor from misinterpreting the double quotation marks embedded in the JSON, you must also escape (precede with a backslash `\` character) each double quotation mark `"` within the JSON data structure itself, as in the following example.
```
C:\> aws ec2 run-instances ^
--image-id ami-12345678 ^
--block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]"
```
Only the outermost double quotation marks are not escaped.
------
# Loading a parameter from a file in the AWS CLI
Some parameters expect file names as arguments, from which the AWS CLI loads the data. Other parameters enable you to specify the parameter value as either text typed on the command line or read from a file. Whether a file is required or optional, you must encode the file correctly so that the AWS CLI can understand it. The file's encoding must match the reading system's default locale. You can determine this by using the Python `locale.getpreferredencoding()` method.
This method is for loading a file for a single parameter. For information on loading multiple parameters with a single file, see [AWS CLI skeletons and input files in the AWS CLI](cli-usage-skeleton.md).
**Note**
By default, Windows PowerShell outputs text as UTF-16, which conflicts with the UTF-8 encoding used by JSON files and many Linux systems. We recommend that you use `-Encoding ascii` with your PowerShell `Out-File` commands to ensure the AWS CLI can read the resulting file.
**Topics**
+ [How to load a parameter from a file](#cli-usage-parameters-file-how)
+ [Binary files](#cli-usage-parameters-file-binary)
+ [Loading a file as a shorthand syntax value](#cli-usage-parameters-file-shorthand)
## How to load a parameter from a file
Sometimes it's convenient to load a parameter value from a file instead of trying to type it all as a command line parameter value, such as when the parameter is a complex JSON string. To specify a file that contains the value, specify a file URL in the following format.
```
file://complete/path/to/file
```
+ The first two slash '/' characters are part of the specification. If the required path begins with a '/', the result is three slash characters: `file:///folder/file`.
+ The URL provides the path to the file that contains the actual parameter content.
+ When using files with spaces or special characters, follow the [quoting and escaping rules](cli-usage-parameters-quoting-strings.md) for your terminal.
The file paths in the following examples are interpreted to be relative to the current working directory.
------
#### [ Linux or macOS ]
```
// Read from a file in the current directory
$ aws ec2 describe-instances --filters file://filter.json
// Read from a file in /tmp
$ aws ec2 describe-instances --filters file:///tmp/filter.json
// Read from a file with a filename with whitespaces
$ aws ec2 describe-instances --filters 'file://filter content.json'
```
------
#### [ Windows command prompt ]
```
// Read from a file in C:\temp
C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json
// Read from a file with a filename with whitespaces
C:\> aws ec2 describe-instances --filters "file://C:\temp\filter content.json"
```
------
The `file://` prefix option supports Unix-style expansions, including "`~/`", "`./`", and "`../`". On Windows, the "`~/`" expression expands to your user directory, stored in the `%USERPROFILE%` environment variable. For example, on Windows 10 you would typically have a user directory under `%USERPROFILE%`.
You must still escape JSON documents that are embedded as the value of another JSON document.
```
$ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json
```
**attributes.json**
```
{
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"
}
```
## Binary files
For commands that take binary data as a parameter, specify that the data is binary content by using the `fileb://` prefix. Commands that accept binary data include:
+ **`aws ec2 run-instances:`** `--user-data` parameter.
+ **`aws s3api put-object:`** `--sse-customer-key` parameter.
+ **`aws kms decrypt:`** `--ciphertext-blob` parameter.
The following example generates a binary 256-bit AES key using a Linux command line tool, and then provides it to Amazon S3 to encrypt an uploaded file server-side.
```
$ dd if=/dev/urandom bs=1 count=32 > sse.key
32+0 records in
32+0 records out
32 bytes (32 B) copied, 0.000164441 s, 195 kB/s
$ aws s3api put-object \
--bucket amzn-s3-demo-bucket \
--key test.txt \
--body test.txt \
--sse-customer-key fileb://sse.key \
--sse-customer-algorithm AES256
{
"SSECustomerKeyMD5": "iVg8oWa8sy714+FjtesrJg==",
"SSECustomerAlgorithm": "AES256",
"ETag": "\"a6118e84b76cf98bf04bbe14b6045c6c\""
}
```
For another example referencing a file containing JSON-formatted parameters, see [Attaching an IAM managed policy to a user](cli-services-iam.md#cli-services-iam-policy).
## Loading a file as a shorthand syntax value
When using shorthand syntax where a value is large or complex, it is often easier to load in a file as a value. To load a file as a shorthand syntax value, the formatting will change slightly. Instead of `key=value` you'll use the `@=` operator instead of the `=` operator. The `@=` signifies to the AWS CLI that the value should be read as a file path and not a string. The following example shows a key-value pair loading a file for its value.
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
The following example demonstrates loading a certificate file for the `aws rolesanywhere create-trust-anchor` command.
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
For more information on shorthand syntax, see [Using shorthand syntax in the AWS CLI](cli-usage-shorthand.md).
# AWS CLI skeletons and input files in the AWS CLI
Most of the AWS CLI commands accept importing parameter inputs from a file. These templates can be generated using the `generate-cli-skeleton` option and then be imported using the `--cli-input-json` and `--cli-input-yaml` parameters.
**Topics**
+ [About AWS CLI skeletons and input files](#cli-usage-skeleton-about)
+ [Generate and import a command skeleton](#cli-usage-skeleton-generate)
+ [Combining input files and command line parameters](#cli-usage-skeleton-combine)
## About AWS CLI skeletons and input files
Most of the AWS Command Line Interface (AWS CLI) commands support the ability to accept parameter inputs from a file using the `--cli-input-json` and `--cli-input-yaml` parameters.
Those same commands use the `--generate-cli-skeleton` parameter to generate a file in either JSON or YAML format with all of the parameters that you can edit and fill in. Then you can run the command with the `--cli-input-json` or `--cli-input-yaml` parameter and point to the filled-in file.
**Important**
Custom AWS CLI commands, such as the [`aws s3` commands](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) don't support either the `--generate-cli-skeleton` or `--cli-input-json` and `--cli-input-yaml` parameters described in this topic. To check if a specific command supports these parameters, run the [`help` command](cli-usage-help.md#cli-usage-help-command) for the command you want to use or refer to the [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/index.html).
The `--generate-cli-skeleton` generates and displays a parameter template that you can customize and use as input on a command. The generated template includes all of the parameters that the command supports.
The `--generate-cli-skeleton` parameter accepts one of the following values:
+ `input` – The generated template includes all input parameters formatted as JSON. This is the default value.
+ `yaml-input` – The generated template includes all input parameters formatted as YAML.
+ `output` – The generated template includes all output parameters formatted as JSON. You can't currently request the output parameters as YAML.
Because the AWS CLI is essentially a "wrapper" around the service's API, the skeleton file expects you to reference all parameters by their underlying API parameter names. This is likely different from the AWS CLI parameter name. For example, an AWS CLI parameter named `user-name` might map to the AWS service's API parameter named `UserName` (notice the altered capitalization and missing dash). We recommend that you use the `--generate-cli-skeleton` option to generate the template with the "correct" parameter names to avoid errors. You can reference the API Reference Guide for the service to see the expected parameter names. You can delete any parameters from the template that are not required and for which you don't want to supply a value.
For example, if you run the following command, it generates the parameter template for the Amazon Elastic Compute Cloud (Amazon EC2) command **run-instances**.
------
#### [ JSON ]
The following example shows how to generate a template formatted in JSON by using the default value (`input`) for the `--generate-cli-skeleton` parameter.
```
$ aws ec2 run-instances --generate-cli-skeleton
```
```
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
```
------
#### [ YAML ]
The following example shows how to generate a template formatted in YAML by using the value `yaml-input` for the `--generate-cli-skeleton` parameter.
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input
```
```
BlockDeviceMappings: # The block device mapping entries.
- DeviceName: '' # The device name (for example, /dev/sdh or xvdh).
VirtualName: '' # The virtual device name (ephemeralN).
Ebs: # Parameters used to automatically set up Amazon EBS volumes when the instance is launched.
DeleteOnTermination: true # Indicates whether the EBS volume is deleted on instance termination.
Iops: 0 # The number of I/O operations per second (IOPS) that the volume supports.
SnapshotId: '' # The ID of the snapshot.
VolumeSize: 0 # The size of the volume, in GiB.
VolumeType: st1 # The volume type. Valid values are: standard, io1, gp2, sc1, st1.
Encrypted: true # Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot.
KmsKeyId: '' # Identifier (key ID, key alias, ID ARN, or alias ARN) for a customer managed KMS key under which the EBS volume is encrypted.
NoDevice: '' # Suppresses the specified device included in the block device mapping of the AMI.
ImageId: '' # The ID of the AMI.
InstanceType: c4.4xlarge # The instance type. Valid values are: t1.micro, t2.nano, t2.micro, t2.small, t2.medium, t2.large, t2.xlarge, t2.2xlarge, t3.nano, t3.micro, t3.small, t3.medium, t3.large, t3.xlarge, t3.2xlarge, t3a.nano, t3a.micro, t3a.small, t3a.medium, t3a.large, t3a.xlarge, t3a.2xlarge, m1.small, m1.medium, m1.large, m1.xlarge, m3.medium, m3.large, m3.xlarge, m3.2xlarge, m4.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m4.10xlarge, m4.16xlarge, m2.xlarge, m2.2xlarge, m2.4xlarge, cr1.8xlarge, r3.large, r3.xlarge, r3.2xlarge, r3.4xlarge, r3.8xlarge, r4.large, r4.xlarge, r4.2xlarge, r4.4xlarge, r4.8xlarge, r4.16xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.8xlarge, r5.12xlarge, r5.16xlarge, r5.24xlarge, r5.metal, r5a.large, r5a.xlarge, r5a.2xlarge, r5a.4xlarge, r5a.8xlarge, r5a.12xlarge, r5a.16xlarge, r5a.24xlarge, r5d.large, r5d.xlarge, r5d.2xlarge, r5d.4xlarge, r5d.8xlarge, r5d.12xlarge, r5d.16xlarge, r5d.24xlarge, r5d.metal, r5ad.large, r5ad.xlarge, r5ad.2xlarge, r5ad.4xlarge, r5ad.8xlarge, r5ad.12xlarge, r5ad.16xlarge, r5ad.24xlarge, x1.16xlarge, x1.32xlarge, x1e.xlarge, x1e.2xlarge, x1e.4xlarge, x1e.8xlarge, x1e.16xlarge, x1e.32xlarge, i2.xlarge, i2.2xlarge, i2.4xlarge, i2.8xlarge, i3.large, i3.xlarge, i3.2xlarge, i3.4xlarge, i3.8xlarge, i3.16xlarge, i3.metal, i3en.large, i3en.xlarge, i3en.2xlarge, i3en.3xlarge, i3en.6xlarge, i3en.12xlarge, i3en.24xlarge, i3en.metal, hi1.4xlarge, hs1.8xlarge, c1.medium, c1.xlarge, c3.large, c3.xlarge, c3.2xlarge, c3.4xlarge, c3.8xlarge, c4.large, c4.xlarge, c4.2xlarge, c4.4xlarge, c4.8xlarge, c5.large, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge, c5.12xlarge, c5.18xlarge, c5.24xlarge, c5.metal, c5d.large, c5d.xlarge, c5d.2xlarge, c5d.4xlarge, c5d.9xlarge, c5d.18xlarge, c5n.large, c5n.xlarge, c5n.2xlarge, c5n.4xlarge, c5n.9xlarge, c5n.18xlarge, cc1.4xlarge, cc2.8xlarge, g2.2xlarge, g2.8xlarge, g3.4xlarge, g3.8xlarge, g3.16xlarge, g3s.xlarge, g4dn.xlarge, g4dn.2xlarge, g4dn.4xlarge, g4dn.8xlarge, g4dn.12xlarge, g4dn.16xlarge, cg1.4xlarge, p2.xlarge, p2.8xlarge, p2.16xlarge, p3.2xlarge, p3.8xlarge, p3.16xlarge, p3dn.24xlarge, d2.xlarge, d2.2xlarge, d2.4xlarge, d2.8xlarge, f1.2xlarge, f1.4xlarge, f1.16xlarge, m5.large, m5.xlarge, m5.2xlarge, m5.4xlarge, m5.8xlarge, m5.12xlarge, m5.16xlarge, m5.24xlarge, m5.metal, m5a.large, m5a.xlarge, m5a.2xlarge, m5a.4xlarge, m5a.8xlarge, m5a.12xlarge, m5a.16xlarge, m5a.24xlarge, m5d.large, m5d.xlarge, m5d.2xlarge, m5d.4xlarge, m5d.8xlarge, m5d.12xlarge, m5d.16xlarge, m5d.24xlarge, m5d.metal, m5ad.large, m5ad.xlarge, m5ad.2xlarge, m5ad.4xlarge, m5ad.8xlarge, m5ad.12xlarge, m5ad.16xlarge, m5ad.24xlarge, h1.2xlarge, h1.4xlarge, h1.8xlarge, h1.16xlarge, z1d.large, z1d.xlarge, z1d.2xlarge, z1d.3xlarge, z1d.6xlarge, z1d.12xlarge, z1d.metal, u-6tb1.metal, u-9tb1.metal, u-12tb1.metal, u-18tb1.metal, u-24tb1.metal, a1.medium, a1.large, a1.xlarge, a1.2xlarge, a1.4xlarge, a1.metal, m5dn.large, m5dn.xlarge, m5dn.2xlarge, m5dn.4xlarge, m5dn.8xlarge, m5dn.12xlarge, m5dn.16xlarge, m5dn.24xlarge, m5n.large, m5n.xlarge, m5n.2xlarge, m5n.4xlarge, m5n.8xlarge, m5n.12xlarge, m5n.16xlarge, m5n.24xlarge, r5dn.large, r5dn.xlarge, r5dn.2xlarge, r5dn.4xlarge, r5dn.8xlarge, r5dn.12xlarge, r5dn.16xlarge, r5dn.24xlarge, r5n.large, r5n.xlarge, r5n.2xlarge, r5n.4xlarge, r5n.8xlarge, r5n.12xlarge, r5n.16xlarge, r5n.24xlarge.
Ipv6AddressCount: 0 # [EC2-VPC] The number of IPv6 addresses to associate with the primary network interface.
Ipv6Addresses: # [EC2-VPC] The IPv6 addresses from the range of the subnet to associate with the primary network interface.
- Ipv6Address: '' # The IPv6 address.
KernelId: '' # The ID of the kernel.
KeyName: '' # The name of the key pair.
MaxCount: 0 # [REQUIRED] The maximum number of instances to launch.
MinCount: 0 # [REQUIRED] The minimum number of instances to launch.
Monitoring: # Specifies whether detailed monitoring is enabled for the instance.
Enabled: true # [REQUIRED] Indicates whether detailed monitoring is enabled.
Placement: # The placement for the instance.
AvailabilityZone: '' # The Availability Zone of the instance.
Affinity: '' # The affinity setting for the instance on the Dedicated Host.
GroupName: '' # The name of the placement group the instance is in.
PartitionNumber: 0 # The number of the partition the instance is in.
HostId: '' # The ID of the Dedicated Host on which the instance resides.
Tenancy: dedicated # The tenancy of the instance (if the instance is running in a VPC). Valid values are: default, dedicated, host.
SpreadDomain: '' # Reserved for future use.
RamdiskId: '' # The ID of the RAM disk to select.
SecurityGroupIds: # The IDs of the security groups.
- ''
SecurityGroups: # [default VPC] The names of the security groups.
- ''
SubnetId: '' # [EC2-VPC] The ID of the subnet to launch the instance into.
UserData: '' # The user data to make available to the instance.
AdditionalInfo: '' # Reserved.
ClientToken: '' # Unique, case-sensitive identifier you provide to ensure the idempotency of the request.
DisableApiTermination: true # If you set this parameter to true, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can.
DryRun: true # Checks whether you have the required permissions for the action, without actually making the request, and provides an error response.
EbsOptimized: true # Indicates whether the instance is optimized for Amazon EBS I/O.
IamInstanceProfile: # The IAM instance profile.
Arn: '' # The Amazon Resource Name (ARN) of the instance profile.
Name: '' # The name of the instance profile.
InstanceInitiatedShutdownBehavior: stop # Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown). Valid values are: stop, terminate.
NetworkInterfaces: # The network interfaces to associate with the instance.
- AssociatePublicIpAddress: true # Indicates whether to assign a public IPv4 address to an instance you launch in a VPC.
DeleteOnTermination: true # If set to true, the interface is deleted when the instance is terminated.
Description: '' # The description of the network interface.
DeviceIndex: 0 # The position of the network interface in the attachment order.
Groups: # The IDs of the security groups for the network interface.
- ''
Ipv6AddressCount: 0 # A number of IPv6 addresses to assign to the network interface.
Ipv6Addresses: # One or more IPv6 addresses to assign to the network interface.
- Ipv6Address: '' # The IPv6 address.
NetworkInterfaceId: '' # The ID of the network interface.
PrivateIpAddress: '' # The private IPv4 address of the network interface.
PrivateIpAddresses: # One or more private IPv4 addresses to assign to the network interface.
- Primary: true # Indicates whether the private IPv4 address is the primary private IPv4 address.
PrivateIpAddress: '' # The private IPv4 addresses.
SecondaryPrivateIpAddressCount: 0 # The number of secondary private IPv4 addresses.
SubnetId: '' # The ID of the subnet associated with the network interface.
InterfaceType: '' # The type of network interface.
PrivateIpAddress: '' # [EC2-VPC] The primary IPv4 address.
ElasticGpuSpecification: # An elastic GPU to associate with the instance.
- Type: '' # [REQUIRED] The type of Elastic Graphics accelerator.
ElasticInferenceAccelerators: # An elastic inference accelerator to associate with the instance.
- Type: '' # [REQUIRED] The type of elastic inference accelerator.
TagSpecifications: # The tags to apply to the resources during launch.
- ResourceType: network-interface # The type of resource to tag. Valid values are: client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, elastic-ip, fleet, fpga-image, host-reservation, image, instance, internet-gateway, launch-template, natgateway, network-acl, network-interface, reserved-instances, route-table, security-group, snapshot, spot-instances-request, subnet, traffic-mirror-filter, traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway.
Tags: # The tags to apply to the resource.
- Key: '' # The key of the tag.
Value: '' # The value of the tag.
LaunchTemplate: # The launch template to use to launch the instances.
LaunchTemplateId: '' # The ID of the launch template.
LaunchTemplateName: '' # The name of the launch template.
Version: '' # The version number of the launch template.
InstanceMarketOptions: # The market (purchasing) option for the instances.
MarketType: spot # The market type. Valid values are: spot.
SpotOptions: # The options for Spot Instances.
MaxPrice: '' # The maximum hourly price you're willing to pay for the Spot Instances.
SpotInstanceType: one-time # The Spot Instance request type. Valid values are: one-time, persistent.
BlockDurationMinutes: 0 # The required duration for the Spot Instances (also known as Spot blocks), in minutes.
ValidUntil: 1970-01-01 00:00:00 # The end date of the request.
InstanceInterruptionBehavior: terminate # The behavior when a Spot Instance is interrupted. Valid values are: hibernate, stop, terminate.
CreditSpecification: # The credit option for CPU usage of the T2 or T3 instance.
CpuCredits: '' # [REQUIRED] The credit option for CPU usage of a T2 or T3 instance.
CpuOptions: # The CPU options for the instance.
CoreCount: 0 # The number of CPU cores for the instance.
ThreadsPerCore: 0 # The number of threads per CPU core.
CapacityReservationSpecification: # Information about the Capacity Reservation targeting option.
CapacityReservationPreference: none # Indicates the instance's Capacity Reservation preferences. Valid values are: open, none.
CapacityReservationTarget: # Information about the target Capacity Reservation.
CapacityReservationId: '' # The ID of the Capacity Reservation.
HibernationOptions: # Indicates whether an instance is enabled for hibernation.
Configured: true # If you set this parameter to true, your instance is enabled for hibernation.
LicenseSpecifications: # The license configurations.
- LicenseConfigurationArn: '' # The Amazon Resource Name (ARN) of the license configuration.
```
------
## Generate and import a command skeleton
**To generate and use a parameter skeleton file**
1. Run the command with the `--generate-cli-skeleton` parameter to produce either JSON or YAML and direct the output to a file to save it.
------
#### [ JSON ]
```
$ aws ec2 run-instances --generate-cli-skeleton input > ec2runinst.json
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input > ec2runinst.yaml
```
------
1. Open the parameter skeleton file in your text editor and remove any of the parameters that you don't need. For example, you might strip the template down to the following. Confirm the file is still valid JSON or YAML after you remove the elements you don't need.
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "",
"KeyName": "",
"SecurityGroups": [
""
],
"InstanceType": "",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: ''
KeyName: ''
SecurityGroups:
- ''
InstanceType:
Monitoring:
Enabled: true
```
------
In this example, we leave the `DryRun` parameter set to `true` to use the Amazon EC2 dry run feature. This feature lets you safely test the command without actually creating or modifying any resources.
1. Fill in the remaining values with values appropriate for your scenario. In this example, we provide the instance type, key name, security group, and identifier of the Amazon Machine Image (AMI) to use. This example assumes the default AWS Region. The AMI `ami-dfc39aef` is a 64-bit Amazon Linux image hosted in the `us-west-2` Region. If you use a different Region, you must [find the correct AMI ID to use](http://aws.amazon.com/amazon-linux-ami/).
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. Run the command with the completed parameters by passing the completed template file to either the `--cli-input-json` or --`cli-input-yaml` parameter by using the `file://` prefix. The AWS CLI interprets the path to be relative to your current working directory. The following example the AWS CLI looks for the file in the current working directory.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
The dry run error indicates that the JSON or YAML is formed correctly and that the parameter values are valid. If other issues are reported in the output, fix them and repeat the previous step until the "`Request would have succeeded`" message is displayed.
1. Now you can set the `DryRun` parameter to `false` to disable dry run.
------
#### [ JSON ]
```
{
"DryRun": false,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: false
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. Run the command, and `run-instances` actually launches an Amazon EC2 instance and displays the details generated by the successful launch. The format of the output is controlled by the `--output` parameter, separately from the format of your input parameter template.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
## Combining input files and command line parameters
An input file can be used for all parameters, or can be combined with parameters specified in the AWS CLI. You can use this feature for settings you frequently reuse in an input file, while keeping your individual settings in the command itself.
The following `aws ec2 run-instances` examples combine the use of an input file and parameters. We provide the instance type, key name, security group, identifier of the Amazon Machine Image (AMI) to use and assume the default AWS Region. The AMI `ami-dfc39aef` is a 64-bit Amazon Linux image hosted in the `us-west-2` Region. If you use a different Region, you must [find the correct AMI ID to use](http://aws.amazon.com/amazon-linux-ami/).
------
#### [ JSON ]
Contents of the JSON file:
```
{
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
Contents of the YAML file:
```
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
The following example uses the input file in combination with the `--dry-run` parameter to perform a dry-run of the command to confirm whether you have the required permissions and have filled out the file with valid values.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
The following example then uses the same input file, but with the `--no-dry-run` parameter to perform the command in full.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --no-dry-run --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --no-dry-run --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
# Using shorthand syntax in the AWS CLI
The AWS Command Line Interface (AWS CLI) can accept many of its option parameters in JSON format. However, it can be tedious to enter large JSON lists or structures on the command line. To make this easier, the AWS CLI also supports a shorthand syntax that enables a simpler representation of your option parameters than using the full JSON format.
**Topics**
+ [Structure parameters with key-value pairs](#shorthand-structure-parameters)
+ [Loading a file as a shorthand syntax value](#shorthand-files)
+ [Using shorthand syntax with the AWS CLI](#shorthand-list-parameters)
## Structure parameters with key-value pairs
The shorthand syntax in the AWS CLI makes it easier for users to input parameters that are flat (non-nested structures). The format is a comma-separated list of key-value pairs. Be sure to use the [quoting](cli-usage-parameters-quoting-strings.md) and escaping rules appropriate for your terminal as shorthand syntax are strings.
------
#### [ Linux or macOS ]
```
--option key1=value1,key2=value2,key3=value3
```
Is equivalent to the following example, formatted in JSON.
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
#### [ Windows ]
```
--option "key1=value1,key2=value2,key3=value3"
```
Is equivalent to the following example, formatted in JSON.
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
There must be no white space between each comma-separated key-value pair. Here is an example of the Amazon DynamoDB `update-table` command with the `--provisioned-throughput` option specified in shorthand.
```
$ aws dynamodb update-table \
--provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 \
--table-name MyDDBTable
```
This is equivalent to the following example formatted in JSON.
```
$ aws dynamodb update-table \
--provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' \
--table-name MyDDBTable
```
## Loading a file as a shorthand syntax value
When a value is large or complex, it is often easier to load in as a value. To load a file as a shorthand syntax value, the formatting will change slightly. Instead of `key=value` you'll use the `@=` operator instead of the `=` operator. The `@=` signifies to the AWS CLI that the value should be read as a file path and not a string. When loading files in shorthand syntax, the usual [AWS CLI file formatting rules apply](cli-usage-parameters-file.md). The following example shows a key-value pair loading a file for its value.
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
The following example demonstrates loading a certificate file for the `aws rolesanywhere create-trust-anchor` command.
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
## Using shorthand syntax with the AWS CLI
You can specify Input parameters in a list form in two ways: JSON or shorthand. The AWS CLI shorthand syntax is designed to make it easier to pass in lists with number, string, or non-nested structures.
The basic format is shown here, where values in the list are separated by a single space.
```
--option value1 value2 value3
```
This is equivalent to the following example, formatted in JSON.
```
--option '[value1,value2,value3]'
```
As previously mentioned, you can specify a list of numbers, a list of strings, or a list of non-nested structures in shorthand. The following is an example of the `stop-instances` command for Amazon Elastic Compute Cloud (Amazon EC2), where the input parameter (list of strings) for the `--instance-ids` option is specified in shorthand.
```
$ aws ec2 stop-instances \
--instance-ids i-1486157a i-1286157c i-ec3a7e87
```
This is equivalent to the following example formatted in JSON.
```
$ aws ec2 stop-instances \
--instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]'
```
The following example shows the Amazon EC2 `create-tags` command, which takes a list of non-nested structures for the `--tags` option. The `--resources` option specifies the ID of the instance to tag.
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3
```
This is equivalent to the following example, formatted in JSON. The JSON parameter is written over multiple lines for readability.
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags '[
{"Key": "My1stTag", "Value": "Value1"},
{"Key": "My2ndTag", "Value": "Value2"},
{"Key": "My3rdTag", "Value": "Value3"}
]'
```
# Enabling and using command prompts in the AWS CLI
You can have the AWS CLI version 2 prompt you commands, parameters, and resources when you run an `aws` command.
**Topics**
+ [How it works](#cli-usage-auto-prompt-about)
+ [Auto-prompt features](#cli-usage-auto-prompt-features)
+ [Auto-prompt modes](#cli-usage-auto-prompt-modes)
+ [Configure auto-prompt](#cli-usage-auto-prompt-configure)
## How it works
If enabled, the auto-prompt enables you to use the **ENTER** key to complete a partially entered command. After pressing the **ENTER** key, commands, parameters, and resources are suggested based on what you continue to type. The suggestions list the name of the command, parameter, or resource on the left and a description of it on the right. To select and use a suggestion, use the arrows keys to highlight a row, and then press the **SPACE** key. When you've finished entering in your command, press **ENTER** to use the command. The following example demonstrates what a suggested list from auto-prompt looks like.
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
## Auto-prompt features
The auto-prompt contains the following useful features:
**Documentation panel**
Provides the help documentation for the current command. To open the documentation, press the **F3** key.
**Command completion**
Suggests `aws` commands to use. To see a list, partially enter the command. The following example is searching for a service starting with the letter `a`.
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
**Parameter completion**
After a command is typed, auto-prompt starts to suggest parameters. The descriptions for the parameters include the value type, and a description of what the parameter is. Required parameters are listed first, and are labeled as required. The following example shows the auto-prompt list of parameters for `aws dynamodb describe-table`.
```
$ aws dynamodb describe-table
> aws dynamodb describe-table
--table-name (required) [string] The name of the table to describe.
--cli-input-json [string] Reads arguments from the JSON string provided. The JSON string follows the format provide...
--cli-input-yaml [string] Reads arguments from the YAML string provided. The YAML string follows the format provide...
--generate-cli-skeleton [string] Prints a JSON skeleton to standard output without sending an API request. If provided wit...
```
**Resource completion**
The auto-prompt makes AWS API calls using available AWS resource properties to suggest resource values. This allows for auto-prompt to suggest possible resources you own when entering in parameters. In the following example auto-prompt lists your table names when filling in the `--table-name` parameter for the `aws dynamodb describe-table` command.
```
$ aws dynamodb describe-table
> aws dynamodb describe-table --table-name
Table1
Table2
Table3
```
**Shorthand completion**
For parameters that use shorthand syntax, auto-prompt suggests values to use. In the following example, auto-prompt lists shorthand syntax values for the `--placement` parameter in the `aws ec2 run-instances` command.
```
$ aws ec2 run-instances
> aws ec2 run-instances --placement
AvailabilityZone= [string] The Availability Zone of the instance. If not specified, an Availability Zone wil...
Affinity= [string] The affinity setting for the instance on the Dedicated Host. This parameter is no...
GroupName= [string] The name of the placement group the instance is in.
PartitionNumber= [integer] The number of the partition the instance is in. Valid only if the placement grou...
```
**File completion**
When filling out parameters in `aws` commands, auto-complete suggests local filenames after using the prefix `file://` or `fileb://`. In the following example, auto-prompt suggests local files after entering in `--item file://` for the `aws ec2 run-instances` command.
```
$ aws ec2 run-instances
> aws ec2 run-instances --item file://
item1.txt
file1.json
file2.json
```
**Region completion**
When using the global parameter `--region`, auto-prompt lists possible Regions to select from. In the following example, auto-prompt suggests Regions in alphabetical order after entering in `--region` for the `aws dynamodb list-tables` command.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region
af-south-1
ap-east-1
ap-northeast-1
ap-northeast-2
```
**Profile completion**
When using the global parameter `--profile`, auto-prompt lists your profiles. In the following example, auto-prompt suggests your profiles after entering in `--profile` for the `aws dynamodb list-tables` command.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --profile
profile1
profile2
profile3
```
**Fuzzy searching**
Complete commands and values that contain a specific set of characters. In the following example, auto-prompt suggests Regions that contain `eu` after entering in `--region eu` for the `aws dynamodb list-tables` command.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region west
eu-west-1
eu-west-2
eu-west-3
us-west-1
```
**History**
To view and run previously used commands in auto-prompt mode, press **CTRL \$1 R**. History lists previous commands that you can select by using the arrow keys. In the following example, the auto-prompt mode history is displayed.
```
$ aws
> aws
dynamodb list-tables
s3 ls
```
## Auto-prompt modes
Auto-prompt for the AWS CLI version 2 has 2 modes that can be configured:
+ **Full mode:** Uses auto-prompt each time you attempt to run an `aws` command, whether you manually call it using the `--cli-auto-prompt` parameter or permanently enabled it. This includes pressing **ENTER** after both a complete command or incomplete command.
+ **Partial mode:** Uses auto-prompt if a command is incomplete or cannot be run due to client-side validation errors. This mode is particular useful if you have pre-existing scripts, runbooks, or you only want to be auto-prompted for commands you are unfamiliar with rather than prompted on every command.
## Configure auto-prompt
To configure auto-prompt you can use the following methods in order of precedence:
+ **Command line options** enable or disable auto-prompt for a single command. Use `--cli-auto-prompt` to call auto-prompt and `--no-cli-auto-prompt` to disable auto-prompt.
+ **Environment variables** use the `aws\$1cli\$1auto\$1prompt` variable.
+ **Shared config files** use the `cli\$1auto\$1prompt` setting.
# Controlling command output in the AWS CLI
This section describes the different ways to control the output from the AWS Command Line Interface (AWS CLI). Customizing the AWS CLI output in your terminal can improve readability, streamline scripting automation and provide easier navigation through larger data sets.
The AWS CLI supports multiple [output formats](cli-usage-output-format.md), including [`json`](cli-usage-output-format.md#json-output), [`text`](cli-usage-output-format.md#text-output), [`yaml`](cli-usage-output-format.md#yaml-output), [`off`](cli-usage-output-format.md#off-output), and [`table`](cli-usage-output-format.md#table-output). Some services have server-side [pagination](cli-usage-pagination.md) for their data and the AWS CLI provides it's own client-side features for additional pagination options.
Lastly, the AWS CLI has both[ server-side and client-side filtering](cli-usage-filter.md) that you can use individually or together to filter your AWS CLI output.
**Topics**
+ [Sensitive output](#cli-usage-output-sensitive)
+ [Server-side vs client-side output options](#cli-usage-output-server-client)
+ [Setting the output format in the AWS CLI](cli-usage-output-format.md)
+ [Structured error output in the AWS CLI](cli-usage-error-format.md)
+ [Using the pagination options in the AWS CLI](cli-usage-pagination.md)
+ [Filtering output in the AWS CLI](cli-usage-filter.md)
## Sensitive output
Some operations of the AWS CLI might return information that could be considered sensitive, including information from environment variables. The exposure of this information might represent a security risk in certain scenarios; for example, the information could be included in continuous integration and continuous deployment (CI/CD) logs. It is therefore important that you review when you are including such output as part of your logs, and suppress the output when not needed.
For additional information about protecting sensitive data, see [Data protection in the AWS CLI](data-protection.md).
Consider the following best practices:
+ Consider programmatically retrieving your secrets from a secrets store, such as AWS Secrets Manager.
+ Review the contents of your build logs to ensure they do not contain sensitive information. Consider approaches such as piping to `/dev/null` or capturing the output as a bash or PowerShell variable to suppress command outputs.
The following is a bash example for redirecting output, but not errors, to `/dev/null`:
```
$ aws s3 ls > /dev/null
```
For specifics on suppressing output for your terminal, see the user documentation of the terminal you use.
+ Consider the access of your logs and scope the access appropriately for your use case.
## Server-side vs client-side output options
The AWS CLI has both[ server-side and client-side filtering](cli-usage-filter.md) that you can use individually or together to filter your AWS CLI output. Server-side filtering is processed first and returns your output for client-side filtering. Server-side filtering is supported by the service API. Client-side filtering is supported by the AWS CLI client using the `--query` parameter.
**Server-side** output options are features directly supported by the AWS service API. Any data that is filtered or paged out is not sent to the client, which can speed up HTTP response times and improve bandwidth for larger data sets.
**Client-side** output options are features created by the AWS CLI. All data is sent to the client, then the AWS CLI filters or pages the content displayed. Client-side operations do not save on speed or bandwidth for larger datasets.
When server-side and client-side options are used together, server-side operations are completed first and then sent to the client for client-side operations. This uses the potential speed and bandwidth savings of server-side options, while using additional AWS CLI features to get your desired output.
# Setting the output format in the AWS CLI
This topic describes the different output formats for the AWS Command Line Interface (AWS CLI). The AWS CLI supports the following output formats:
+ **[`json`](#json-output)** – The output is formatted as a [JSON](https://json.org/) string.
+ **[`yaml`](#yaml-output)** – The output is formatted as a [YAML](https://yaml.org/) string.
+ **[`yaml-stream`](#yaml-stream-output)** – The output is streamed and formatted as a [YAML](https://yaml.org/) string. Streaming allows for faster handling of large data types.
+ **[`text`](#text-output)** – The output is formatted as multiple lines of tab-separated string values. This can be useful to pass the output to a text processor, like `grep`, `sed`, or `awk`.
+ **[`table`](#table-output)** – The output is formatted as a table using the characters \$1\$1- to form the cell borders. It typically presents the information in a "human-friendly" format that is much easier to read than the others, but not as programmatically useful.
+ **[`off`](#off-output)** – The output suppresses all command output to stdout. This is useful in automation scripts and CI/CD pipelines where you only need to check the command's exit code without processing the output.
## How to select the output format
As explained in the [configuration](cli-chap-configure.md) topic, you can specify the output format in three ways:
+ **Using the `output` option in a named profile in the `config` file** – The following example sets the default output format to `text`.
```
[default]
output=text
```
+ **Using the `AWS_DEFAULT_OUTPUT` environment variable** – The following output sets the format to `table` for the commands in this command line session until the variable is changed or the session ends. Using this environment variable overrides any value set in the `config` file.
```
$ export AWS_DEFAULT_OUTPUT="table"
```
+ **Using the `--output` option on the command line ** – The following example sets the output of only this one command to `json`. Using this option on the command overrides any currently set environment variable or the value in the `config` file.
```
$ aws swf list-domains --registration-status REGISTERED --output json
```
**Important**
The output type you specify changes how the `--query` option operates:
If you specify `--output text`, the output is paginated *before* the `--query` filter is applied, and the AWS CLI runs the query once on *each page* of the output. Due to this, the query includes the first matching element on each page which can result in unexpected extra output. To additionally filter the output, you can use other command line tools such as `head` or `tail`.
If you specify `--output json`, `--output yaml`, or `--output yaml-stream` the output is completely processed as a single, native structure before the `--query` filter is applied. The AWS CLI runs the query only once against the entire structure, producing a filtered result that is then output.
## JSON output format
[JSON](https://json.org) is the default output format of the AWS CLI. Most programming languages can easily decode JSON strings using built-in functions or with publicly available libraries. You can combine JSON output with the [--query option](cli-usage-filter.md) in powerful ways to filter and format the AWS CLI JSON-formatted output.
For more advanced filtering that you might not be able to do with `--query`, you can consider `jq`, a command line JSON processor. You can download it and find the official tutorial at [http://stedolan.github.io/jq/](http://stedolan.github.io/jq/).
The following is an example of JSON output.
```
$ aws iam list-users --output json
```
```
{
"Users": [
{
"Path": "/",
"UserName": "Admin",
"UserId": "AIDA1111111111EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/Admin",
"CreateDate": "2014-10-16T16:03:09+00:00",
"PasswordLastUsed": "2016-06-03T18:37:29+00:00"
},
{
"Path": "/backup/",
"UserName": "backup-user",
"UserId": "AIDA2222222222EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/backup/backup-user",
"CreateDate": "2019-09-17T19:30:40+00:00"
},
{
"Path": "/",
"UserName": "cli-user",
"UserId": "AIDA3333333333EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/cli-user",
"CreateDate": "2019-09-17T19:11:39+00:00"
}
]
}
```
## YAML output format
[YAML](https://yaml.org) is a good choice for handling the output programmatically with services and tools that emit or consume [YAML](https://yaml.org)-formatted strings, such as CloudFormation with its support for [YAML-formatted templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html).
For more advanced filtering that you might not be able to do with `--query`, you can consider `yq`, a command line YAML processor. You can download `yq` in the [yq repository](https://github.com/mikefarah/yq) on *GitHub*.
The following is an example of YAML output.
```
$ aws iam list-users --output yaml
```
```
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## YAML stream output format
The `yaml-stream` format takes advantage of the [YAML](https://yaml.org) format while providing more responsive/faster viewing of large data sets by streaming the data to you. You can start viewing and using YAML data before the entire query downloads.
For more advanced filtering that you might not be able to do with `--query`, you can consider `yq`, a command line YAML processor. You can download `yq` in the [yq repository](https://github.com/mikefarah/yq) on *GitHub*.
The following is an example of `yaml-stream` output.
```
$ aws iam list-users --output yaml-stream
```
```
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
The following is an example of `yaml-stream` output in conjunction with using the `--page-size` parameter to paginate the streamed YAML content.
```
$ aws iam list-users --output yaml-stream --page-size 2
```
```
- IsTruncated: true
Marker: ab1234cdef5ghi67jk8lmo9p/q012rs3t445uv6789w0x1y2z/345a6b78c9d00/1efgh234ij56klmno78pqrstu90vwxyx
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## Text output format
The `text` format organizes the AWS CLI output into tab-delimited lines. It works well with traditional Unix text tools such as `grep`, `sed`, and `awk`, and the text processing performed by PowerShell.
The `text` output format follows the basic structure shown below. The columns are sorted alphabetically by the corresponding key names of the underlying JSON object.
```
IDENTIFIER sorted-column1 sorted-column2
IDENTIFIER2 sorted-column1 sorted-column2
```
The following is an example of `text` output. Each field is tab separated from the others, with an extra tab where there is an empty field.
```
$ aws iam list-users --output text
```
```
USERS arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 / AIDA1111111111EXAMPLE Admin
USERS arn:aws:iam::123456789012:user/backup/backup-user 2019-09-17T19:30:40+00:00 /backup/ AIDA2222222222EXAMPLE backup-user
USERS arn:aws:iam::123456789012:user/cli-user 2019-09-17T19:11:39+00:00 / AIDA3333333333EXAMPLE cli-user
```
The fourth column is the `PasswordLastUsed` field, and is empty for the last two entries because those users never sign in to the AWS Management Console.
**Important**
*We strongly recommend that if you specify `text` output, you also always use the [`--query`](cli-usage-filter.md) option to ensure consistent behavior*.
This is because the text format alphabetically orders output columns by the key name of the underlying JSON object returned by the AWS service, and similar resources might not have the same key names. For example, the JSON representation of a Linux-based Amazon EC2 instance might have elements that are not present in the JSON representation of a Windows-based instance, or vice versa. Also, resources might have key-value elements added or removed in future updates, altering the column ordering. This is where `--query` augments the functionality of the `text` output to provide you with complete control over the output format.
In the following example, the command specifies which elements to display and *defines the ordering* of the columns with the list notation `[key1, key2, ...]`. This gives you full confidence that the correct key values are always displayed in the expected column. Finally, notice how the AWS CLI outputs `None` as the value for keys that don't exist.
```
$ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]'
```
```
Admin arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 AIDA1111111111EXAMPLE
backup-user arn:aws:iam::123456789012:user/backup-user 2019-09-17T19:30:40+00:00 None AIDA2222222222EXAMPLE
cli-user arn:aws:iam::123456789012:user/cli-backup 2019-09-17T19:11:39+00:00 None AIDA3333333333EXAMPLE
```
The following example shows how you can use `grep` and `awk` with the `text` output from the `aws ec2 describe-instances` command. The first command displays the Availability Zone, current state, and the instance ID of each instance in `text` output. The second command processes that output to display only the instance IDs of all running instances in the `us-west-2a` Availability Zone.
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text
```
```
us-west-2a running i-4b41a37c
us-west-2a stopped i-a071c394
us-west-2b stopped i-97a217a0
us-west-2a running i-3045b007
us-west-2a running i-6fc67758
```
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | grep us-west-2a | grep running | awk '{print $3}'
```
```
i-4b41a37c
i-3045b007
i-6fc67758
```
The following example goes a step further and shows not only how to filter the output, but how to use that output to automate changing instance types for each stopped instance.
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId]' --output text |
> grep stopped |
> awk '{print $2}' |
> while read line;
> do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "m1.medium"}';
> done
```
The `text` output can also be useful in PowerShell. Because the columns in `text` output are tab delimited, you can easily split the output into an array by using PowerShell's ``t` delimiter. The following command displays the value of the third column (`InstanceId`) if the first column (`AvailabilityZone`) matches the string `us-west-2a`.
```
PS C:\>aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text |
%{if ($_.split("`t")[0] -match "us-west-2a") { $_.split("`t")[2]; } }
```
```
-4b41a37c
i-a071c394
i-3045b007
i-6fc67758
```
Notice that although the previous example does show how to use the `--query` parameter to parse the underlying JSON objects and pull out the desired column, PowerShell has its own ability to handle JSON, if cross-platform compatibility isn't a concern. Instead of handling the output as text, as most command shells require, PowerShell lets you use the `ConvertFrom-JSON` cmdlet to produce a hierarchically structured object. You can then directly access the member you want from that object.
```
(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId
```
**Tip**
If you output text, and filter the output to a single field using the `--query` parameter, the output is a single line of tab-separated values. To get each value onto a separate line, you can put the output field in brackets, as shown in the following examples.
Tab separated, single-line output:
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].GroupName"
```
```
HRDepartment Developers SpreadsheetUsers LocalAdmins
```
Each value on its own line by putting `[GroupName]` in brackets:
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].[GroupName]"
```
```
HRDepartment
Developers
SpreadsheetUsers
LocalAdmins
```
## Table output format
The `table` format produces human-readable representations of complex AWS CLI output in a tabular form.
```
$ aws iam list-users --output table
```
```
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
| ListUsers |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
|| Users ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| Arn | CreateDate | PasswordLastUsed | Path | UserId | UserName ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| arn:aws:iam::123456789012:user/Admin | 2014-10-16T16:03:09+00:00 | 2016-06-03T18:37:29+00:00 | / | AIDA1111111111EXAMPLE | Admin ||
|| arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 | | /backup/ | AIDA2222222222EXAMPLE | backup-user ||
|| arn:aws:iam::123456789012:user/cli-user | 2019-09-17T19:11:39+00:00 | | / | AIDA3333333333EXAMPLE | cli-user ||
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
You can combine the `--query` option with the `table` format to display a set of elements preselected from the raw output. Notice the output differences between dictionary and list notations: in the first example, column names are ordered alphabetically, and in the second example, unnamed columns are ordered as defined by the user. For more information about the `--query` option, see [Filtering output in the AWS CLI](cli-usage-filter.md).
```
$ aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table
```
```
------------------------------------------------------
| DescribeVolumes |
+------------+----------------+--------------+-------+
| AZ | ID | InstanceId | Size |
+------------+----------------+--------------+-------+
| us-west-2a| vol-e11a5288 | i-a071c394 | 30 |
| us-west-2a| vol-2e410a47 | i-4b41a37c | 8 |
+------------+----------------+--------------+-------+
```
```
$ aws ec2 describe-volumes --query 'Volumes[*].[VolumeId,Attachments[0].InstanceId,AvailabilityZone,Size]' --output table
```
```
----------------------------------------------------
| DescribeVolumes |
+--------------+--------------+--------------+-----+
| vol-e11a5288| i-a071c394 | us-west-2a | 30 |
| vol-2e410a47| i-4b41a37c | us-west-2a | 8 |
+--------------+--------------+--------------+-----+
```
## Off output format
The `off` format suppresses all command output to stdout. This is useful in automation scripts and CI/CD pipelines where you only need to check the command's exit code without processing the output. Error messages are still displayed on stderr.
The following example shows how the `off` format suppresses successful output. You can check the exit code to determine success:
```
$ aws s3api list-buckets --output off
$ echo $?
0
```
This is particularly useful in shell scripts where you want to verify a resource exists without capturing output:
```
#!/bin/bash
if aws s3api head-bucket --bucket my-bucket --output off 2>/dev/null; then
echo "Bucket exists"
else
echo "Bucket does not exist"
fi
```
**Note**
The `off` format only suppresses stdout. Errors are still written to stderr.
# Structured error output in the AWS CLI
This topic describes the structured error output formats for the AWS Command Line Interface (AWS CLI). The CLI writes errors to stderr and supports the following formats:
+ **[`enhanced`](#cli-error-format-enhanced)** (default) – Error message with additional details displayed inline. Use for human-readable debugging.
+ **[`json`](#cli-error-format-json)** – The output is formatted as a [JSON](https://json.org/) string with all error fields. Use for automation and scripting.
+ **[`yaml`](#cli-error-format-yaml)** – The output is formatted as a [YAML](https://yaml.org/) string with all error fields. Use for automation and scripting.
+ **[`text`](#cli-error-format-text)** – Formats errors using the text formatter. Use for quick visual scanning.
+ **[`table`](#cli-error-format-table)** – Formats errors using the table formatter. Use for quick visual scanning.
+ **[`legacy`](#cli-error-format-legacy)** – Original error format without structured details. Use for backward compatibility.
## Configuring error format
You can configure the error format using any of the following methods:
Command-line flag
```
$ aws --cli-error-format json
```
Configuration file (`~/.aws/config`)
```
[default]
cli_error_format = json
```
Environment variable
```
$ export AWS_CLI_ERROR_FORMAT=yaml
```
## Error output formats
The following sections describe each format:
### Enhanced format (default)
The enhanced format displays error messages with additional details inline for simple values. For complex structures, the format provides a hint to use JSON or YAML.
**Example: Missing region configuration**
```
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
```
**Example: Nonexistent Lambda function with additional fields**
```
aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345
Additional error details:
Type: User
```
The "Additional error details" section displays only fields that are defined in the service's error shape model. Unmodeled fields from the error response are not shown.
**Example: Complex error fields**
```
An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]
Additional error details:
CancellationReasons:
Use "--cli-error-format json" or another error format to see the full details.
```
### JSON format
The JSON format provides a structured representation with all error fields.
**Example: Missing region configuration**
```
{
"Code": "NoRegion",
"Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}
```
**Example: Nonexistent Lambda function**
```
{
"Code": "ResourceNotFoundException",
"Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345",
"Type": "User"
}
```
### YAML format
The YAML format provides a structured representation with all error fields.
**Example: Missing region configuration**
```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```
**Example: Nonexistent Lambda function**
```
Code: ResourceNotFoundException
Message: "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345"
Type: User
```
### Text format
The text format uses the same formatter as successful command output.
**Example: Nonexistent Lambda function**
```
ResourceNotFoundException Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 User
```
### Table format
The table format uses the same formatter as successful command output.
**Example: Nonexistent Lambda function**
```
------------------------------------------------------------------------------------------------------------------------------------|
| error |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
| Code | Message | Type |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
| ResourceNotFoundException | Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 | User |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
```
### Legacy format
The legacy format provides the original error format without structured details. This format does not include the "An error occurred (ErrorCode):" prefix for CLI exceptions.
**Example: Missing region configuration**
```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```
**Example: Nonexistent Lambda function**
```
An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345
```
**Note**
Errors now consistently include the `aws: [ERROR]:` prefix for CLI exceptions. Earlier versions did not always include this prefix.
The following exceptions always use the legacy format regardless of the configured error format:
`UnknownArgumentError` – Displays usage information
Keyboard interrupts (`KeyboardInterrupt`)
## Complete example
The following example shows a command with JSON error formatting:
```
$ aws lambda get-function \
--function-name nonexistent-function-12345 \
--cli-error-format json
```
Output (stderr):
```
{
"Code": "ResourceNotFoundException",
"Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345",
"Type": "User"
}
```
The `Type` field is a modeled error member defined in the Lambda service's error shape. Only fields defined in the service's error model are included in the structured error output.
# Using the pagination options in the AWS CLI
This topic describes the different ways to paginate output from the AWS Command Line Interface (AWS CLI).
There are primarily two ways to control pagination from the AWS CLI.
+ [Using server-side pagination parameters.](#cli-usage-pagination-serverside)
+ [Using your default output client-side paging program](#cli-usage-pagination-clientside).
Server-side pagination parameters process first and any output is sent to client-side pagination.
## Server-side pagination
For most commands that return a large list of items, the AWS CLI has multiple server-side options to control the number of items included in the output when the AWS CLI calls a service's API to populate the list. Server-side pagination in the AWS CLI is enabled by the AWS service API, therefore these options only work if the service API enables them.
**Topics**
+ [--no-paginate](#cli-usage-pagination-nopaginate)
+ [--page-size](#cli-usage-pagination-pagesize)
+ [--max-items](#cli-usage-pagination-maxitems)
+ [--starting-token](#cli-usage-pagination-startingtoken)
By default, the AWS CLI uses a page size determined by the individual service and retrieves all available items. For example, Amazon S3 has a default page size of 1000. If you run `aws s3api list-objects` on an Amazon S3 bucket that contains 3,500 objects, the AWS CLI automatically makes four calls to Amazon S3, handling the service-specific pagination logic for you in the background and returning all 3,500 objects in the final output.
For information about whether a specific command has server-side pagination, see the [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/index.html).
### How to use the --no-paginate parameter
The `--no-paginate` option disables following pagination tokens on the client side. When using a command, by default the AWS CLI automatically makes multiple calls to return all possible results to create pagination. One call for each page. Disabling pagination has the AWS CLI only call once for the first page of command results.
For example, if you run `aws s3api list-objects` on an Amazon S3 bucket that contains 3,500 objects, the AWS CLI only makes the first call to Amazon S3, returning only the first 1,000 objects in the final output.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-paginate
{
"Contents": [
...
```
### How to use the --page-size parameter
If you see issues when running list commands on a large number of resources, the default page size might be too high. This can cause calls to AWS services to exceed the maximum allowed time and generate a "timed out" error. You can use the `--page-size` option to specify that the AWS CLI request a smaller number of items from each call to the AWS service. The AWS CLI still retrieves the full list, but performs a larger number of service API calls in the background and retrieves a smaller number of items with each call. This gives the individual calls a better chance of succeeding without a timeout. Changing the page size doesn't affect the output; it affects only the number of API calls that need to be made to generate the output.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--page-size 100
{
"Contents": [
...
```
### How to use the --max-items parameter
To include fewer items at a time in the AWS CLI output, use the `--max-items` option. The AWS CLI still handles pagination with the service as described previously, but prints out only the number of items at a time that you specify.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100
{
"NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
"Contents": [
...
```
### How to use the --starting-token parameter
If the number of items output (`--max-items`) is fewer than the total number of items returned by the underlying API calls, the output includes a `NextToken` that you can pass to a subsequent command to retrieve the next set of items. The following example shows how to use the `NextToken` value returned by the previous example, and enables you to retrieve the second 100 items.
**Note**
The parameter `--starting-token` cannot be null or empty. If the previous command does not return a `NextToken` value, there are no more items to return and you do not need to call the command again.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100 \
--starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
"Contents": [
...
```
The specified AWS service might not return items in the same order each time you call. If you specify different values for `--page-size` and `--max-items`, you can get unexpected results with missing or duplicated items. To prevent this, use the same number for `--page-size` and `--max-items` to sync the AWS CLI pagination with the pagination of the underlying service. You can also retrieve the whole list and perform any necessary paging operations locally.
## Client-side pager
AWS CLI version 2 provides the use of a client-side pager program for output. By default, this feature returns all output through your operating system’s default pager program.
In order of precedence, you can specify the output pager in the following ways:
+ Using the `cli_pager` setting in the `config` file in the `default` or named profile.
+ Using the `AWS_PAGER` environment variable.
+ Using the `PAGER` environment variable.
In order of precedence, you can disable all use of an external paging program in the following ways:
+ Use the `--no-cli-pager` command line option to disable the pager for a single command use.
+ Set the `cli_pager` setting or `AWS_PAGER` variable to an empty string.
**Topics**
+ [cli\$1pager](#cli-usage-pagination-clipager)
+ [AWS\$1PAGER](#cli-usage-pagination-awspager)
+ [--no-cli-pager](#cli-usage-pagination-noclipager)
+ [Pager flags](#cli-usage-pagination-flags)
### How to use the cli\$1pager setting
You can save your frequently used configuration settings and credentials in files that are maintained by the AWS CLI. Settings in a name profile take precedence over settings in the `default` profile. For more information on configuration settings, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md).
The following example sets the default output pager to the `less` program.
```
[default]
cli_pager=less
```
The following example sets the default to disable the use of a pager.
```
[default]
cli_pager=
```
### How to set the AWS\$1PAGER environment variable
The following example sets the default output pager to the `less` program. For more information on environment variables, see [Configuring environment variables for the AWS CLI](cli-configure-envvars.md).
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### How to use the --no-cli-pager option
To disable the use of a pager on a single command, use the `--no-cli-pager` option. For more information on command line options, see [Command line options in the AWS CLI](cli-configure-options.md).
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-cli-pager
{
"Contents": [
...
```
### How to use pager flags
You can specify flags to use automatically with your paging program. Flags are dependent on the paging program you use. The below examples are for the typical defaults of `less` and `more`.
------
#### [ Linux and macOS ]
If you do not specify otherwise, the pager AWS CLI version 2 uses by default is `less`. If you don't have the `LESS` environment variable set, the AWS CLI version 2 uses the `FRX` flags. You can combine flags by specifying them when setting the AWS CLI pager.
The following example uses the `S` flag. This flag then combines with the default `FRX` flags to create a final `FRXS` flag.
```
$ export AWS_PAGER="less -S"
```
If you don't want any of the `FRX` flags, you can negate them. The following example negates the `F` flag to create a final `RX` flag.
```
$ export AWS_PAGER="less -+F"
```
For more information on `less` flags see [less](http://manpages.org/less/1#options) on *manpages.org*.
------
#### [ Windows ]
If you do not specify otherwise, the pager AWS CLI version 2 uses by default is `more` with no additional flags.
The following example uses the `/c` parameter.
```
C:\> setx AWS_PAGER "more /c"
```
For more information on `more` flags, see `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)` on *Microsoft Docs*.
------
# Filtering output in the AWS CLI
The AWS Command Line Interface (AWS CLI) has both server-side and client-side filtering that you can use individually or together to filter your AWS CLI output. Server-side filtering is processed first and returns your output for client-side filtering.
+ Server-side filtering is supported by the API, and you usually implement it with a `--filter` parameter. The service only returns matching results which can speed up HTTP response times for large data sets.
+ Client-side filtering is supported by the AWS CLI client using the `--query` parameter. This parameter has capabilities the server-side filtering might not have.
**Topics**
+ [Server-side filtering](#cli-usage-filter-server-side)
+ [Client-side filtering](#cli-usage-filter-client-side)
+ [Combining server-side and client-side filtering](#cli-usage-filter-combining)
+ [Additional resources](#cli-usage-filter-resources)
## Server-side filtering
Server-side filtering in the AWS CLI is provided by the AWS service API. The AWS service only returns the records in the HTTP response that match your filter, which can speed up HTTP response times for large data sets. Since server-side filtering is defined by the service API, the parameter names and functions vary between services. Some common parameter names used for filtering are:
+ `--filter` such as [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html) and [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html).
+ `--filters` such as [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html), [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html), and [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html).
+ Names starting with the word `filter`, for example `--filter-expression` for the [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html) command.
For information about whether a specific command has server-side filtering and the filtering rules, see the [AWS CLI version 2 reference guide](https://docs.aws.amazon.com/cli/latest/reference/index.html).
## Client-side filtering
The AWS CLI provides built-in JSON-based client-side filtering capabilities with the `--query` parameter. The `--query` parameter is a powerful tool you can use to customize the content and style of your output. The `--query` parameter takes the HTTP response that comes back from the server and filters the results before displaying them. Since the entire HTTP response is sent to the client before filtering, client-side filtering can be slower than server-side filtering for large data-sets.
Querying uses [JMESPath syntax](https://jmespath.org/) to create expressions for filtering your output. To learn JMESPath syntax, see [Tutorial](https://jmespath.org/tutorial.html) on the *JMESPath website*.
**Important**
The output type you specify changes how the `--query` option operates:
If you specify `--output text`, the output is paginated *before* the `--query` filter is applied, and the AWS CLI runs the query once on *each page* of the output. Due to this, the query includes the first matching element on each page which can result in unexpected extra output. To additionally filter the output, you can use other command line tools such as `head` or `tail`.
If you specify `--output json`, `--output yaml`, or `--output yaml-stream` the output is completely processed as a single, native structure before the `--query` filter is applied. The AWS CLI runs the query only once against the entire structure, producing a filtered result that is then output.
**Topics**
+ [Before you start](#cli-usage-filter-client-side-output)
+ [Identifiers](#cli-usage-filter-client-side-identifiers)
+ [Selecting from a list](#cli-usage-filter-client-side-select-list)
+ [Filtering nested data](#cli-usage-filter-client-side-nested)
+ [Flattening results](#cli-usage-filter-client-side-specific-flattening)
+ [Filtering for specific values](#cli-usage-filter-client-side-specific-values)
+ [Piping expressions](#cli-usage-filter-client-side-pipe)
+ [Filtering for multiple identifier values](#cli-usage-filter-client-side-miltiselect-list)
+ [Adding labels to identifier values](#cli-usage-filter-client-side-multiselect-hash)
+ [Functions](#cli-usage-filter-client-side-functions)
+ [Advanced `--query` examples](#cli-usage-filter-client-side-advanced)
### Before you start
**Note**
These filter expression examples are written for basic linux-like shells. When using these examples, be sure to use the correct quoting rules for your terminal shell. The way your terminal interprets your inputs can vastly change what is sent to the AWS CLI. How your terminal reads single quotes`'`, double quotes `"`, or backticks ``` can change how content is read.
For more information, see [Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md).
The following JSON output shows an example of what the `--query` parameter can produce. The output describes three Amazon EBS volumes attached to separate Amazon EC2 instances.
#### Example output
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
### Identifiers
Identifier are the labels for output values. When creating filters, you use identifiers to narrow down your query results. In the following output example, all identifiers such as `Volumes`, `AvailabilityZone`, and `AttachTime` are highlighted.
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
For more information, see [Identifiers](https://jmespath.org/specification.html#identifiers ) on the *JMESPath website*.
### Selecting from a list
A list or array is an identifier that is followed by a square bracket "`[`" such as `Volumes` and `Attachments` in the [Before you start](#cli-usage-filter-client-side-output).
**Syntax**
```
[ ]
```
To filter through all output from an array, you can use the wildcard notation. [Wildcard](http://jmespath.org/specification.html#wildcard-expressions) expressions are expressions used to return elements using the `*` notation.
The following example queries all `Volumes` content.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
To view a specific volume in the array by index, you call the array index. For example, the first item in the `Volumes` array has an index of 0, resulting in the `Volumes[0]` query. For more information about array indexes, see [index expressions](http://jmespath.org/specification.html#index-expressions) on the *JMESPath website*.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0]'
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
```
To view a specific range of volumes by index, use `slice` with the following syntax, where **start** is the starting array index, **stop** is the index where the filter stops processing, and **step** is the skip interval.
**Syntax**
```
[::]
```
If any of these are omitted from the slice expression, they use the following default values:
+ Start – The first index in the list, 0.
+ Stop – The last index in the list.
+ Step – No step skipping, where the value is 1.
To return only the first two volumes, you use a start value of 0, a stop value of 2, and a step value of 1 as shown in the following example.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0:2:1]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
}
]
```
Since this example contains default values, you can shorten the slice from `Volumes[0:2:1]` to `Volumes[:2]`.
The following example omits default values and returns every two volumes in the entire array.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
Steps can also use negative numbers to filter in the reverse order of an array as shown in the following example.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::-2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
]
```
For more information, see [Slices](https://jmespath.org/specification.html#slices) on the *JMESPath website*.
### Filtering nested data
To narrow the filtering of the `Volumes[*]` for nested values, you use subexpressions by appending a period and your filter criteria.
**Syntax**
```
.
```
The following example shows all `Attachments` information for all volumes.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments'
[
[
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
]
]
```
To filter further into the nested values, append the expression for each nested indentifier. The following example lists the `State` for all `Volumes`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[*].State'
[
[
"attached"
],
[
"attached"
],
[
"attached"
]
]
```
### Flattening results
For more information, see [SubExpressions](https://jmespath.org/specification.html#subexpressions) on the *JMESPath website*.
You can flatten the results for `Volumes[*].Attachments[*].State` by removing the wildcard notation resulting in the `Volumes[*].Attachments[].State` query. Flattening often is useful to improve the readablity of results.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].State'
[
"attached",
"attached",
"attached"
]
```
For more information, see [Flatten](https://jmespath.org/specification.html#flatten) on the *JMESPath website*.
### Filtering for specific values
To filter for specific values in a list, you use a filter expression as shown in the following syntax.
**Syntax**
```
? ]
```
Expression comparators include `==`, `!=`, `<`, `<=`, `>`, and `>=` . The following example filters for the `VolumeIds` for all `Volumes` in an `Attached``State`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId'
[
[
"vol-e11a5288"
],
[
"vol-2e410a47"
],
[
"vol-a1b3c7nd"
]
]
```
This can then be flattened resulting in the following example.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]'
[
"vol-e11a5288",
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
The following example filters for the `VolumeIds` of all `Volumes` that have a size less than 20.
```
$ aws ec2 describe-volumes \
--query 'Volumes[?Size < `20`].VolumeId'
[
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
For more information, see [Filter Expressions](https://jmespath.org/specification.html#filterexpressions) on the *JMESPath website*.
### Piping expressions
You can pipe results of a filter to a new list, and then filter the result with another expression using the following syntax:
**Syntax**
```
| ]
```
The following example takes the filter results of the `Volumes[*].Attachments[].InstanceId` expression and outputs the first result in the array.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId | [0]'
"i-a071c394"
```
This example does this by first creating the array from the following expression.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId'
"i-a071c394",
"i-4b41a37c",
"i-1jd73kv8"
```
And then returns the first element in that array.
```
"i-a071c394"
```
For more information, see [Pipe Expressions](https://jmespath.org/specification.html#pipe-expressions) on the *JMESPath website*.
### Filtering for multiple identifier values
To filter for multiple identifiers, you use a multiselect list by using the following syntax:
**Syntax**
```
[].[, ]
```
In the following example, `VolumeId` and `VolumeType` are filtered in the `Volumes` list resulting in the following expression.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType]'
[
[
"vol-e11a5288",
"standard"
],
[
"vol-2e410a47",
"standard"
],
[
"vol-a1b3c7nd",
"standard"
]
]
```
To add nested data to the list, you add another multiselect list. The following example expands on the previous example by also filtering for `InstanceId` and `State` in the nested `Attachments` list. This results in the following expression.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]'
[
[
"vol-e11a5288",
"standard",
[
[
"i-a071c394",
"attached"
]
]
],
[
"vol-2e410a47",
"standard",
[
[
"i-4b41a37c",
"attached"
]
]
],
[
"vol-a1b3c7nd",
"standard",
[
[
"i-1jd73kv8",
"attached"
]
]
]
]
```
To be more readable, flatten out the expression as shown in the following example.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]'
[
"vol-e11a5288",
"standard",
[
"i-a071c394",
"attached"
],
"vol-2e410a47",
"standard",
[
"i-4b41a37c",
"attached"
],
"vol-a1b3c7nd",
"standard",
[
"i-1jd73kv8",
"attached"
]
]
```
For more information, see [Multiselect list](https://jmespath.org/specification.html#multiselectlist) on the *JMESPath website*.
### Adding labels to identifier values
To make this output easier to read, use a multiselect hash with the following syntax.
**Syntax**
```
[].{