Parameter

Description

Examples

[BUCKET_NAME]/[FOLDER]/[OBJECT]

Name of the bucket, folder, object(s) to list.

If not specified, objects in current location are listed.

Change the current location with command cd.

To specify the parent folder, use '..'

Wildcard character can be used (i.e. * and ?) like in Windows dir.

If object name have spaces, they must be surrounded by  quotation marks (") on the command line.

ls (list all objects in current path. If the current path is the root it will list all buckets)

ls mybucket (list all objects in mybucket)

ls mybucket/myfolder (list all objects in mybucket/myfolder)

ls ../myfolder (list all objects in ../myfolder)

ls mybucket/*.txt (list all objects with extension txt in mybucket, in the root folder)

ls mybucket/myfolder/*.txt (list all objects with extension txt in mybucket/myfolder/)

ls "mybucket/my folder/*.txt" (list all objects with extension txt in mybucket/my folder/, using quotation marks)

-s

Recursive listing, e.g. include all subfolders.

ls -s (list all objects in current path and subfolders. If the current path is the root it will list all buckets and every object in them)

ls mybucket -s (list all objects in mybucket and in all subfolders)

ls mybucket/myfolder/*.txt (list all objects with extension txt in mybucket/myfolder/ and subfolders)

-d

Include subfolders (=directories) in the listing.

ls mybucket -s -d (list all objects and directories in mybucket and in all subfolders)

-od

Only include subfolders (=directories) in the listing, do not list other objects.

ls mybucket -od (list all folders that are in mybucket)

ls mybucket -s -od (list all folders that are in mybucket and in all subfolders)

-md5

Include the object's MD5 value in the listing.

ls mybucket -md5

-r

Regular expression. This flag specifies that [BUCKET_NAME]/[FOLDER]/[OBJECT] must be treated as a regular expression.

ls "mybucket/my folder/.*\.txt|.*\.vsn" (list all objects with extension txt or vsn in mybucket/my folder/)

ls mybucket/^r.* (list all objects starting with 'r' in mybucket)

-bytes

Show the object's size in bytes, instead of KB or MB.

ls mybucket -s -bytes

-ext

Extended listing. Metadata and ACLs are shown beneath other object's information.

ls mybucket -ext

-sep:SEP

Use SEP as fields' separator. If not specified, the default separator used is a blank space.

ls mybucket -sep:, (use comma as fields' separator)

ls mybucket -sep:"* *" (use '* *' as fields' separator)

-showmeta:
"META"

Include specified object metadata in the listing output. Wildcard character can be used (i.e. * and ?). Multiple metadata headers should be separated by |. If this flag is not specified, by default, no metadata is shown.
 
Note that showing metadata in the listing output is much slower as each object must be queried separately.

ls mybucket -showmeta:* (include ALL the metadata headers in the output)

ls mybucket -showmeta:"cache-control" (include the cache-control header in the output for objects that have it)

ls mybucket -showmeta:"cache-control|x-amz-server-side​-encryption" (include the cache-control and x-amz-server-side​-encryption metadata headers in the output for objects that have it)

ls mybucket -showmeta:"x-amz-meta-*" (include all the metadata headers that start with x-amz-meta- in the output for objects that have it)

ls mybucket -showmeta:* -ext (include ALL the metadata headers in the output in extended format, metadata shown beneath other object's information)

-showacl:
"ACL"

Include specified ACL permissions in the listing output. Wildcard character can be used (i.e. * and ?). Multiple ACLs should be separated by |. If this flag is not specified, by default, no ACL is shown.
 
Note that showing ACLs in the listing output is much slower as each object must be queried separately.

ls mybucket -showacl:* (include all ACL object permissions in the output)

ls mybucket -showacl:allusers (include AllUsers ACL object permissions in the output)

ls mybucket -showacl:user (include user ACL object permissions in the output)

ls mybucket -showacl:user|allusers (include user and alluser ACL object permissions in the output)

-maxkeys:X

Request only X objects per HTTP request.

ls mybucket -maxkeys:10

-cond:
"FILTER"

Filter condition. Only include objects in the output matching the specified condition. More info on filter condition syntax and variables.

ls mybucket -s -cond:"extract_value(cache-control,'max-age') > 0" -meta:cache-control (list all objects (recursive) with cache-control:max-age value > 0 in the metadata and include the cache-control header in the output)

ls mybucket -s -cond:"size = 0" (list all objects (recursive) of size equal to zero)

ls mybucket -s -cond:"name starts_with 'a'" (list all objects (recursive) with name starting with a)

ls mybucket -s -cond:"name starts_with 'a' and size > 0" (list all objects (recursive) with name starting with a and size > 0)

More info on filter condition syntax and variables

-sum

Show summary only, e.g. total amount of objects and total size, do not list each object separately.

ls mybucket -s -sum (show summary of all objects in mybucket and in all subfolders)

-grp:GROUP

Group objects by GROUP in the output.
 
GROUP can be one of the following values:
ym (i.e. -grp:ym) Group objects by year and month.
ymd (i.e. -grp:ymd) Group objects by year, month and day.
ext (i.e. -grp:ext) Group objects by object's extension.
subf (i.e. -grp:subf) Group objects by subfolder.
 
GROUP can also be a generic condition, e.g. -grp:s3_sizemb groups object by size in MB, or -grp:cache-control groups object by cache-control value. See Filter Conditions for details.

ls mybucket -s -grp:subf (list all objects in mybucket and subfolders and group output by subfolder)
ls mybucket -s -grp:ext (list all objects in mybucket and subfolders and group output by object's extension)
ls mybucket -s -grp:ymd (list all objects in mybucket and subfolders and group output by year, month and day)
ls mybucket -s -grp:ymd -sum (show summary only of all objects in mybucket and subfolders and group summary by year, month and day)
ls mybucket -s -grp:cache-control -sum (show summary only of all objects in mybucket and subfolders and group summary by cache-control value)
ls mybucket -s -grp:cache-control -sum -cond:"extract_value(cache-control,'max-age') > 0" (show summary only of all objects in mybucket and subfolders which have the cache-control:max-age value larger than 0 and group summary by cache-control value)
ls mybucket -s -grp:s3_sizemb -sum (show summary only of all objects in mybucket and subfolders and group summary by object size in megabytes)

-inclversions

Include all object versions (for buckets with object versioning enabled)

ls mybucket -s -inclversions (list all object versions in mybucket and subfolders)

-onlyprev

Include only previous object versions (for buckets with object versioning enabled)

ls mybucket -s -onlyprev (list previous object versions in mybucket and subfolders)

-showverids

Include object version IDs in the in the listing output when object versions are listed (option -inclversions).

ls mybucket -s -inclversions -showverids (list all object versions in mybucket with their version ID)

-include:INCL

Only include objects matching specified mask (Wildcards). Separate multiple masks with "|".

ls mybucket -include:*.jpg (list all jpg files in mybucket)

ls mybucket -include:*.jpg|*.gif (list all jpg and gif files in mybucket)

-exclude:EXCL

Exclude objects matching specified mask (Wildcards). Separate multiple masks with "|".

ls mybucket -exclude:*.jpg (list all files in mybucket but exclude jpg files)

ls mybucket -exclude:*.jpg|*.gif (list all files in mybucket but exclude jpg files)

-rinclude:INCL

Only include objects matching specified mask (Regular Expression).

ls mybucket -rinclude:a(x|y|z)b (list files in mybucket matching axb, ayb and azb)

ls mybucket -rinclude:*.(gif|bmp|jpg) (list files in mybucket matching anything ending with .gif, .bmp or .jpg)

ls mybucket -rinclude:"IMGP[0-9]{4}.jpg" (list files in mybucket ending with .jpg , starting with IMG and followed by a four-digit number)

-rexclude:EXCL

Exclude objects matching specified mask (Regular Expression).

ls mybucket -rexclude:[abc] (list all files in mybucket but exclude files containing a, b or c)

-inclenc
-exclenc

Include only server-side encrypted files.
Exclude server-side encrypted files.

ls mybucket -inclenc (list all files in mybucket that are server-side encrypted)

ls mybucket -exclenc (list all files in mybucket that are NOT server-side encrypted)

-inclrr
-exclrr

Include only reduced redundancy files.

Exclude reduced redundancy files.

ls mybucket -inclrr (list all files in mybucket that are reduced redundancy)

ls mybucket -exclrr (list all files in mybucket that are NOT reduced redundancy)

-inclia
-exclia

Include only infrequent access files.

Exclude infrequent access files.

ls mybucket -inclia (list all files in mybucket that are infrequent access)

ls mybucket -exclia (list all files in mybucket that are NOT infrequent access)

-inclgl
-exclgl

Include only Glacier files.

Exclude Glacier files.

ls mybucket -inclgl (list all files in mybucket that are part of Amazon Glacier)

ls mybucket -exclgl (list all files in mybucket that are NOT part of Amazon Glacier)

-inclle
-exclle

Include only client-side (locally) encrypted files.

Exclude only client-side (locally) encrypted files.

ls mybucket -inclle (list all files in mybucket that were locally encrypted)

ls mybucket -exclle (list all files in mybucket that were NOT locally encrypted)