CLI Output Formats & --query/JMESPath

The AWS CLI can render results as JSON, a table, or plain text, and --query filters them with JMESPath before they print. This makes the CLI a fast companion to your SDK code for checks and scripting.

Summary

Every AWS CLI command supports --output with three formats: json, table, and text.

--query takes a JMESPath expression - a query language for JSON - and reshapes the response before it is displayed.

Together they turn verbose API responses into exactly the value you want, which is perfect for shell scripts and quick verification.

The CLI and the SDKs are complementary. Use the CLI for one-off checks and glue scripts; use boto3 or the AWS SDK v3 for application logic.

boto3 even shares the JMESPath engine through paginator filtering, so a query you write for the CLI transfers directly to Python.

Recipe

Shape and filter output without post-processing tools.

# Choose an output format
aws ec2 describe-instances --output table
aws ec2 describe-instances --output json      # default if configured
 
# Filter with JMESPath: just the instance IDs
aws ec2 describe-instances \
  --query "Reservations[].Instances[].InstanceId" \
  --output text
 
# Reshape into named columns
aws ec2 describe-instances \
  --query "Reservations[].Instances[].{ID:InstanceId,State:State.Name}" \
  --output table

When to reach for this:

• You want one value (an ID, an ARN) to pipe into another command.
• You need a readable table for a quick human check.
• You are writing a shell script and want to avoid jq.
• You want to prototype a filter before porting it into SDK code.

Working Example

The same "list running instance IDs" done with the CLI, then in both SDKs.

# CLI: text output is script-friendly (no quotes, tab-separated)
aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" \
  --query "Reservations[].Instances[].InstanceId" \
  --output text

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2")
 
# boto3 shares the JMESPath engine via paginator.search().
paginator = ec2.get_paginator("describe_instances")
pages = paginator.paginate(
    Filters=[{"Name": "instance-state-name", "Values": ["running"]}]
)
 
ids = list(pages.search("Reservations[].Instances[].InstanceId"))
print(ids)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({});
 
// v3 has no JMESPath helper, so filter in-language.
const res = await ec2.send(
  new DescribeInstancesCommand({
    Filters: [{ Name: "instance-state-name", Values: ["running"] }],
  })
);
 
const ids = (res.Reservations ?? []).flatMap((r) =>
  (r.Instances ?? []).map((i) => i.InstanceId)
);
console.log(ids);

What this demonstrates:

• The CLI --query string and boto3's paginator.search() use the identical JMESPath expression.
• --output text yields tab-separated values that pipe cleanly into other shell commands.
• v3 has no built-in JMESPath, so the same shape is produced with flatMap/map.
• The --filters argument filters server-side; --query filters client-side after the response arrives.

Deep Dive

How It Works

• --query runs entirely client-side after the full API response returns; it does not reduce what AWS sends.
• --filters (where a command supports it) filters server-side and is cheaper for large result sets.
• JMESPath [] flattens nested arrays; {Name:expr} builds a reshaped object with chosen keys.
• --output text prints values tab-separated with no JSON punctuation, ideal for read, xargs, and loops.
• --output table renders an ASCII table for humans; --output json preserves full structure for machines.

Output Formats at a Glance

Common JMESPath Patterns

# First element
--query "Reservations[0].Instances[0].InstanceId"
 
# Filter by a field, then project
--query "Reservations[].Instances[?State.Name=='running'].InstanceId"
 
# Rename fields into columns
--query "Buckets[].{Name:Name,Created:CreationDate}"
 
# Sort and take a slice
--query "sort_by(Volumes, &Size)[-3:].VolumeId"

Gotchas

• --query does not reduce data transfer - It runs after the whole response arrives, so it is not a substitute for server-side --filters on huge lists. Fix: use --filters to limit results, then --query to shape them.
• Quoting on Windows - Single quotes inside --query break in cmd.exe. Fix: use double quotes outside and escape inner quotes, or run in PowerShell/bash.
• text output and empty results - An empty --query result prints nothing, which can look like an error. Fix: check the exit code, not just stdout.
• Assuming v3 has JMESPath - The AWS SDK for JavaScript v3 has no query helper. Fix: filter with map/filter/flatMap in TypeScript.
• Pagination cut-off - A raw describe-* call returns only one page, so --query sees partial data. Fix: the CLI auto-paginates by default, but in SDK code use a paginator.
• None vs missing keys - JMESPath returns null for missing fields, which prints as None/blank in text. Fix: guard for nulls before using values downstream.

Alternatives

FAQs

Related

• AWS CLI Setup Basics - install the CLI and set a default output format.
• The AWS CLI as the SDK's Shared Credential Backbone - how CLI checks and SDK code share credentials.
• Named Profiles & Multi-Account Config - target the right account for these queries.
• AWS CLI Setup Best Practices - conventions for scripting the CLI safely.

Stack versions: This page was written for the AWS CLI v2, boto3 1.43.x (Python 3.10+), and the AWS SDK for JavaScript v3 (Node.js 18+).