Command line options in the Amazon CLI
In the Amazon CLI, command line options are global parameters you can use to override the default configuration settings, any corresponding profile setting, or environment variable setting for that single command. You can't use command line options to directly specify credentials, although you can specify which profile to use.
Topics
How to use command line options
Most command line options are simple strings, such as the profile name
profile1
in the following example:
$
aws s3 ls --profile
profile1
amzn-s3-demo-bucket1 amzn-s3-demo-bucket2 ...
Each option that takes an argument requires a space or equals sign (=) separating the argument from the option name. If the argument value is a string that contains a space, you must use quotation marks around the argument. For details on argument types and formatting for parameters, see Specifying parameter values in the Amazon CLI.
Amazon CLI supported global command line options
In the Amazon CLI you can use the following command line options to override the default configuration settings, any corresponding profile setting, or environment variable setting for that single command.
- --ca-bundle
<string>
-
Specifies the certificate authority (CA) certificate bundle to use when verifying SSL certificates.
If defined, this option overrides the value for the profile setting
ca_bundle
and theAWS_CA_BUNDLE
environment variable. - --cli-auto-prompt
-
Enables auto-prompt mode for a single command. As the following examples show, you can specify it at any point.
$
aws --cli-auto-prompt
$
aws dynamodb --cli-auto-prompt
$
aws dynamodb describe-table --cli-auto-prompt
This option overrides the
aws_cli_auto_prompt
environment variable and thecli_auto_prompt
profile setting.For information on the Amazon CLI version 2 auto-prompt feature, see Enabling and using command prompts in the Amazon CLI.
- --cli-binary-format
-
Specifies how the Amazon CLI version 2 interprets binary input parameters. It can be one of the following values:
-
base64 – This is the default value. An input parameter that is typed as a binary large object (BLOB) accepts a base64-encoded string. To pass true binary content, put the content in a file and provide the file's path and name with the
fileb://
prefix as the parameter's value. To pass base64-encoded text contained in a file, provide the file's path and name with thefile://
prefix as the parameter's value. -
raw-in-base64-out – Default for the Amazon CLI version 1. If the setting's value is
raw-in-base64-out
, files referenced using thefile://
prefix is read as text and then the Amazon CLI attempts to encode it to binary.
This overrides the
cli_binary_format
file configuration setting.$
aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-function \ --invocation-type Event \ --payload '{ "name": "Bob" }' \ response.json
If you reference a binary value in a file using the
fileb://
prefix notation, the Amazon CLI always expects the file to contain raw binary content and does not attempt to convert the value.If you reference a binary value in a file using the
file://
prefix notation, the Amazon CLI handles the file according to the currentcli_binary_format
setting. If that setting's value isbase64
(the default when not explicitly set), the Amazon CLI expects the file to contain base64-encoded text. If that setting's value israw-in-base64-out
, the Amazon CLI expects the file to contain raw binary content. -
- --cli-connect-timeout
<integer>
-
Specifies the maximum socket connect time in seconds. If the value is set to zero (0), the socket connect waits indefinitely (is blocking) and doesn't timeout.
- --cli-read-timeout
<integer>
-
Specifies the maximum socket read time in seconds. If the value is set to zero (0) the socket read waits indefinitely (is blocking) and doesn't timeout.
- --color
<string>
-
Specifies support for color output. Valid values are
on
,off
, andauto
. The default value isauto
. - --debug
-
A Boolean switch that enables debug logging. The Amazon CLI by default provides cleaned up information regarding any successes or failures regarding command outcomes in the command output. The
--debug
option provides the full Python logs. This includes additionalstderr
diagnostic information about the operation of the command that can be useful when troubleshooting why a command provides unexpected results. To easily view debug logs, we suggest sending the logs to a file to more easily search the information. You can do this by using one of the following.To send only the
stderr
diagnostic information, append2> debug.txt
wheredebug.txt
is the name you want to use for your debug file:$
aws
2>servicename
commandname
options
--debugdebug.txt
To send both the output and
stderr
diagnostic information, append&> debug.txt
wheredebug.txt
is the name you want to use for your debug file:$
aws
&>servicename
commandname
options
--debugdebug.txt
- --endpoint-url
<string>
-
Specifies the URL to send the request to. For most commands, the Amazon CLI automatically determines the URL based on the selected service and the specified Amazon Region. However, some commands require that you specify an account-specific URL. You can also configure some Amazon services to host an endpoint directly within your private VPC, which might then need to be specified.
The following command example uses a custom Amazon S3 endpoint URL.
$
aws s3 ls --endpoint-url
http://localhost:4567
Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. The Amazon CLI endpoint configuration settings take precedence in the following order:
-
The
--endpoint-url
command line option. -
If enabled, the
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS
global endpoint environment variable or profile settingignore_configure_endpoint_urls
to ignore custom endpoints. -
The value provided by a service-specific environment variable
AWS_ENDPOINT_URL_<SERVICE>
, such asAWS_ENDPOINT_URL_DYNAMODB
. -
The values provided by the
AWS_USE_DUALSTACK_ENDPOINT
,AWS_USE_FIPS_ENDPOINT
, andAWS_ENDPOINT_URL
environment variables. -
The service-specific endpoint value provided by the
endpoint_url
setting within aservices
section of the sharedconfig
file. -
The value provided by the
endpoint_url
setting within aprofile
of the sharedconfig
file. -
use_dualstack_endpoint
,use_fips_endpoint
, andendpoint_url
settings. -
Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.
-
- --no-cli-auto-prompt
-
Disables auto-prompt mode for a single command.
$
aws dynamodb describe-table --table-name Table1 --no-cli-auto-prompt
This option overrides the
aws_cli_auto_prompt
environment variable and thecli_auto_prompt
profile setting.For information on the Amazon CLI version 2 auto-prompt feature, see Enabling and using command prompts in the Amazon CLI.
- --no-cli-pager
-
A Boolean switch that disables using a pager for the output of the command.
- --no-paginate
-
A Boolean switch that disables the multiple calls the automatically Amazon CLI makes to receive all command results that creates pagination of the output. This means only the first page of your output is displayed.
- --no-sign-request
-
A Boolean switch that disables signing the HTTP requests to the Amazon service endpoint. This prevents credentials from being loaded.
- --no-verify-ssl
-
By default, the Amazon CLI uses SSL when communicating with Amazon services. For each SSL connection and call, the Amazon CLI verifies the SSL certificates. Using this option overrides the default behavior of verifying SSL certificates.
Warning
This option is not best practice. If you use
--no-verify-ssl
, your traffic between your client and Amazon services is no longer secured. This means your traffic is a security risk and vulnerable to man-in-the-middle exploits. If you're having issues with certificates, it's best to resolve those issues instead. For certificate troubleshooting steps, see SSL certificate errors. - --output
<string>
-
Specifies the output format to use for this command. You can specify any of the following values:
-
yaml-stream – The output is streamed and formatted as a YAML
string. Streaming allows for faster handling of large data types. -
text – 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
, orawk
. -
table – The output is formatted as a table using the characters +|- 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.
- --profile
<string>
-
Specifies the named profile to use for this command. To set up additional named profiles, you can use the
aws configure
command with the--profile
option.$
aws configure --profile
<profilename>
- --query
<string>
-
Specifies a JMESPath query
to use in filtering the response data. For more information, see Filtering output in the Amazon CLI. - --region
<string>
-
Specifies which Amazon Region to send this command's Amazon request to. For a list of all of the Regions that you can specify, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.
- --version
-
A Boolean switch that displays the current version of the Amazon CLI program that is running.
Common uses of command line options
Common uses for command line options include checking your resources in multiple Amazon Regions, and changing the output format for legibility or ease of use when scripting. In the following examples, we run the describe-instances command against each Region until we find which Region our instance is in.
$
aws ec2 describe-instances --output table --region
us-west-1
------------------- |DescribeInstances| +-----------------+
$aws ec2 describe-instances --output table --region
us-west-2
------------------------------------------------------------------------------ | DescribeInstances | +----------------------------------------------------------------------------+ || Reservations || |+-------------------------------------+------------------------------------+| || OwnerId | 012345678901 || || ReservationId | r-abcdefgh || |+-------------------------------------+------------------------------------+| ||| Instances ||| ||+------------------------+-----------------------------------------------+|| ||| AmiLaunchIndex | 0 ||| ||| Architecture | x86_64 ||| ...