aws s3 ls: List S3 Buckets and Objects in CI

List buckets, prefixes, and objects, with sizes and counts.

aws s3 ls lists buckets when given no path, or objects and prefixes when given an s3:// URI. In CI it is used to confirm an artifact landed, count objects, or verify a deploy prefix before invalidating a CDN.

Common flags

--recursive - list all objects beneath a prefix
--human-readable - print sizes as KB/MB/GB
--summarize - print total object count and size
--page-size - control API page size for large buckets

Example in CI

Confirm artifacts exist under a release prefix.

shell

aws s3 ls s3://${ARTIFACT_BUCKET}/releases/${VERSION}/ --recursive --human-readable --summarize

Common errors in CI

An error occurred (AccessDenied) - role lacks s3:ListBucket on the bucket
Unable to locate credentials - configure OIDC role auth
The specified bucket does not exist - wrong name or region

Key takeaways

aws s3 ls lists buckets with no path, or objects with an s3:// URI.
Use --recursive --summarize to count and size a prefix in CI.
Listing requires s3:ListBucket, distinct from object-level permissions.