aws s3 ls: Usage, Options & Common CI Errors

List buckets, prefixes, and objects in S3 from the command line.

aws s3 ls lists your buckets, or the objects and common prefixes under a bucket path. It is the quick way to confirm an upload landed or to inspect a prefix in CI.

What it does

With no argument, aws s3 ls lists all buckets in the account. Given an s3:// URI it lists the objects and "folders" (common prefixes) directly under that path; with --recursive it lists every object beneath it. --human-readable and --summarize add friendly sizes and totals.

Common usage

Terminal

# List all buckets
aws s3 ls

# List the contents of a prefix
aws s3 ls s3://my-bucket/releases/

# Recurse with human-readable sizes and a total
aws s3 ls s3://my-bucket/releases/ --recursive --human-readable --summarize

Common error in CI: empty output vs AccessDenied

A common confusion: aws s3 ls s3://bucket/missing/ prints nothing and exits 0 when the prefix simply has no objects - not an error. A real failure looks like "An error occurred (AccessDenied) when calling the ListObjectsV2 operation", meaning the role lacks s3:ListBucket on the bucket (note: listing needs s3:ListBucket on the bucket ARN, not s3:GetObject on objects). Fix: grant s3:ListBucket on arn:aws:s3:::bucket with a prefix condition, and do not treat empty output as a credentials problem.

Key options

Option	Purpose
--recursive	List all objects under the prefix
--human-readable	Friendly file sizes
--summarize	Print total object count and size
--page-size	Objects per API call (large buckets)