Generating AWS CLI skeleton and input parameters from a JSON or YAML input file
You can create and consume YAML input skeleton templates only with version 2 of the AWS CLI. If you use AWS CLI version 1, you can create and consume only JSON input skeleton templates.
Most of the AWS Command Line Interface (AWS CLI) commands support the ability to accept
all of the parameter
input from a file using the --cli-input-json and --cli-input-yaml
parameters.
Those same commands helpfully provide 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 relevant
--cli-input-json or --cli-input-yaml parameter and point to
the filled-in file.
Several AWS CLI commands don't map directly to individual AWS API operations, such
as
the aws s3 commands. Such
commands don't support either the --generate-cli-skeleton or
--cli-input-json and --cli-input-yaml parameters described
in this topic. If you don't know whether a specific command supports these parameters,
run the following command, replacing the service and
command names with the ones you're interested in.
$ aws service command helpThe output includes a Synopsis section that shows the parameters that the
specified command supports.
$aws iam list-users help... SYNOPSIS list-users ... [--cli-input-json | --cli-input-yaml] ... [--generate-cli-skeleton <value>] ...
The --generate-cli-skeleton parameter causes the command not to run, but
instead to generate and display a parameter template that you can customize and use
as input
on a later 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 also 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.
To generate and use a parameter skeleton file
-
Run the command with the
--generate-cli-skeletonparameter to produce either JSON or YAML and direct the output to a file to save it. -
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. Be sure that the file is still valid JSON or YAML after you remove the elements you don't need.
In this example, we leave the
DryRunparameter set totrueto use the Amazon EC2 dry run feature. This feature lets you safely test the command without actually creating or modifying any resources. -
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-dfc39aefis a 64-bit Amazon Linux image hosted in theus-west-2Region. If you use a different Region, you must find the correct AMI ID to use. -
Run the command with the completed parameters by passing the completed template file to either the
--cli-input-jsonor --cli-input-yamlparameter by using thefile://prefix. The AWS CLI interprets the path to be relative to your current working directory, so in the following example that displays only the file name with no path, it looks for the file directly in the current working directory.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. -
Now you can set the
DryRunparameter tofalseto disable dry run. -
Run the command, and
run-instancesactually launches an EC2 instance and displays the details generated by the successful launch. The format of the output is controlled by the--outputparameter, separately from the format of your input parameter template.
