**This documentation is for Version 1 of the AWS CLI only.** We announced the upcoming end-of-support for the AWS CLI version 1. We recommend that you migrate to the AWS CLI version 2. For dates, additional details, and information on how to migrate, see the [announcement](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/). For documentation related to Version 2 of the AWS CLI, see the [Version 2 User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). # 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) + [ ## Remote files ](#cli-usage-parameters-file-remote) + [ ## 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. **Note** This behavior is disabled automatically for parameters that already expect a URL, such as parameter that identifies a CloudFormation template URL. You can also disable this behavior by disabling the [`cli_follow_urlparam`](cli-configure-files.md#cli-config-cli_follow_urlparam) setting in your AWS CLI configuration file. 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\"" } ``` ## Remote files The AWS CLI also supports loading parameters from a file hosted on the internet with an `http://` or `https://` URL. The following example references a file stored in an Amazon S3 bucket. This allows you to access parameter files from any computer, but it does require that the container is publicly accessible. ``` $ aws ec2 run-instances \ --image-id ami-12345678 \ --block-device-mappings http://amzn-s3-demo-bucket.s3.amazonaws.com/filename.json ``` The preceding example assumes that the file `filename.json` contains the following JSON data. ``` [ { "DeviceName": "/dev/sdb", "Ebs": { "VolumeSize": 20, "DeleteOnTermination": false, "VolumeType": "standard" } } ] ``` 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).