In the AWS CLI Commands – Bulk Operations article, we provided a number of useful AWS bulk operation commands. It briefly talked about the command output options, but didn’t cover the details. We’ll use this article to provide more information about how to format the AWS CLI outputs.
Output Formats
AWS CLI supports the following formats:
- json
- yaml or yaml-stream
- text
- table
The yaml formats require AWS CLI version 2 to be installed. If you are still using an earlier version, you can download the latest version of CLI from AWS CLI Installation User Guide.
Format Specification
To specify the output format, you can add --output <format name> at the end of the command. For example,
aws ec2 describe-regions --output text
It will override the default format setting and display output in the text format. If your preferred output format is always the text format, then you should set up this format as the default format in your configure file.
To set up the default output format, it’s worthwhile to spend a bit time on knowing the profile configuration first. AWS CLI supports two types of profiles, the default profile and named profile.
- To set up default profile configuration, run aws configure
- To set up named profile configuration, run aws configure --profile <profile name>
Both profile configurations enable you to specify the default output format. It’s usually the last command-line question when you execute the configuration commands.
Another way to set up the configuration is to edit the physical config file. For example, if you are using Windows OS, you can find the config file under C:\Users\user_name\.aws\config. The default profile is defined under the [default] section of the file. The named profiles are defined under the [profile <profile_name>] sections. All these sections will have the output = <format name> line. You can set your preferred format per each profile. If you need to edit the output formats for a large number of profiles, it’s easier to edit them directly via the config file.
Once you’ve specified the default output formats, the CLI command output will follow your configuration to display outputs. When you have multiple output specifications defined, the superseding rules are:
- command specified output supersedes the config file specified output
- named profile output supersedes the default profile output
For example, if you set default profile’s output as text, a named profile A’s output as json.
- aws ec2 describe-regions, will display the output format as text;
- aws ec2 describe-regions --profile A, will display the output format as json;
- aws ec2 describe-regions --profile A --output yaml, will display the output format as yaml.
Output Filter
Once you’ve specified the format, the CLI output will display in your desired format. But it may provide overwhelming amount of data in the output, especially when you have a large number of service instances. This is when the filtering comes handy.
There are two type of filtering’s: Server-side Filtering and Client-side Filtering. Server-side filtering uses --filter as the parameter, whereas client-side filtering uses --query. The --query type of filter provides more functionalities but can be slow if there are large amount data in the output, since it’s client-end filtering. When you use --query, it’s like:
aws ec2 describe-regions
--query "Regions[*].[Endpoint,RegionName]"
Or you can also combine --filters with --query, and it’s like:
aws ec2 describe-regions
--filters "Name=region-name,Values=ap-southeast-2"
--query "Regions[*].[Endpoint,RegionName]"
There are many ways you can tweak the filter parameters to suit your need. For more information and examples, see Filtering AWS CLI Output
