Common Amazon CLI parameter types - Amazon Command Line Interface
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

Common Amazon CLI parameter types

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 Getting help with the Amazon CLI.


String parameters can contain alphanumeric characters, symbols, and white spaces from the 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 to prevent unexpected results.

Some string parameters can accept binary data from a file. See Binary files for an example.


Timestamps are formatted according to the ISO 8601 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-DDThh:mm:ss.sssTZD (UTC), for example, 2014-10-01T20:30:00.000Z

  • YYYY-MM-DDThh:mm:ss.sssTZD (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 and represents the number of seconds since midnight, January 1, 1970 UTC.

You can set the timestamp format by using the cli_timestamp_format file setting.


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 to prevent unexpected results.

$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium


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.


An unsigned, whole number.

$ aws ec2 describe-spot-price-history --max-items 5

Binary / blob (binary large object) and streaming blob

In the Amazon CLI version 1, to pass a value to a parameter with type blob, you must specify a path to a local file that contains the binary data. The path should not contain any protocol identifier, such as http:// or file://. The specified path is interpreted as being relative to the current working directory. For example, the --body parameter for aws s3api put-object is a blob.

$ aws s3api put-object --bucket my-bucket --key testimage.png --body /tmp/image.png

Streaming blobs such as aws cloudsearchdomain upload-documents are not prefixed by file:// or fileb://. 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 \ --content-type application/json \ --documents document-batch.json


A set of key-value pairs specified in JSON or by using the CLI's shorthand syntax. 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 on GitHub.

$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}' { "Item": { "name": { "S": "John" }, "id": { "N": "1" } } }



Shorthand syntax 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:

--option '"value"'
--option 123 --option 123.456
--option true
--option null
--option '["value1", "value2", "value3"]' --option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]'
--option '{"key": "value"}' --option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}'