tencent cloud

Querying Bucket/Object List - ls
Download PDF
Last updated: 2025-05-09 18:27:39
Querying Bucket/Object List - ls
Last updated: 2025-05-09 18:27:39
Download PDF
The ls command is used to query the list of buckets, objects in a bucket, and objects in a directory.
Note:
If you need to list files in the bucket, when you perform authorization policy, set action to cos:HeadBucket, cos:GetBucket.
If you need to list historical version information (import --all-versions), when you perform authorization policy, set action to cos:HeadBucket, cos:GetBucketVersioning, cos:GetBucketObjectVersions.
If you need to list buckets under the account, when you perform authorization policy, set action to cos:GetService.
For more authorizations, please refer to CAM-Enabled API.

Command Syntax

./coscli ls [cos://<bucket-name>[/prefix/]] [flag]
ls includes the following parameters:
Parameter Format
Description
Example
cos://<bucket-name>
Specifies the optional target bucket, which is accessible by using the bucket alias or bucket name configured in the configuration file as detailed in Download and Installation Configuration. If you use the bucket name for access, you also need to include the endpoint flag.
Access with the bucket alias: cos://example-alias
Access with the bucket name: cos://examplebucket-1250000000
/prefix/
Specifies a directory (optional).
/picture/
ls includes the following optional flags:
Flag Abbreviation
Flag Name
Description
-h
--help
Views the usage of this command.
None
--include
Includes specific objects.
None
--exclude
Excludes specific objects.
-r
--recursive
Specifies whether to traverse directories recursively and list all objects.
None
--limit
Specifies the maximum quantity to be listed. (If 0 or no value is configured, the default value is 10000)
None
--all-versions
List all versions of objects. It is available only after version control is enabled for a bucket. Add display fields VersionId, IsLatest and Delete Marker for parameters when listing historical versions.
Note:
--include and --exclude support standard regular expressions. You can use regular expressions to filter objects that meet your requirements.
When using zsh, you may need to add double quotes at both ends of the pattern string.
./coscli ls cos://bucket1 -r --include ".*\\.mp4$"
For other common options of this command (such as switching buckets and user accounts), see common options.

Examples

Listing all buckets of the current account

./coscli ls
The returned information includes the bucket name, region, creation time, and total number of buckets. Below is an example:
           BUCKET NAME          |     REGION      |     CREATE DATE
--------------------------------+-----------------+-----------------------
  examplebucket-1250000000      | ap-nanjing      | 2022-01-01T00:00:00Z
--------------------------------+-----------------+-----------------------
                                  TOTAL BUCKETS:  |          2
                                ------------------+-----------------------

Listing objects

Listing all objects in the bucket1 bucket

./coscli ls cos://bucket1
The returned information includes the object key (the unique identifier of the object in the bucket), storage class, last update time, object size, and total number of objects. Below is an example:
     KEY     |   TYPE   |       LAST MODIFIED       |                ETAG                |      SIZE       | RESTORESTATUS  
-------------+----------+---------------------------+------------------------------------+-----------------+----------------
  test.txt   | STANDARD | 2024-06-05T15:03:37+08:00 | "a3bc6c9058109f8da48d41a5ab9abc7c" | 4.88 KB         |                
-------------+----------+---------------------------+------------------------------------+-----------------+----------------
                                                                                           TOTAL OBJECTS:  |       1        
                                                                                         ------------------+----------------

Listing all objects and subdirectories in the picture directory in the bucket1 bucket

./coscli ls cos://bucket1/picture/
General listing only returns the data at the level of the query path, without expanding subpaths. Below is an example:
          KEY            |   TYPE   |       LAST MODIFIED       |                ETAG                |      SIZE       | RESTORESTATUS  
-------------------------+----------+---------------------------+------------------------------------+-----------------+----------------
  picture/a4431470f55662 | STANDARD | 2024-06-05T15:03:58+08:00 | "ed0430c5f27e76605e0555c260478112" | 358.00 B        |                
  picture/e98c6cefa4abd6 | STANDARD | 2024-06-05T15:03:58+08:00 | "bd5a4bd7248e7dfdb796383bee60470b" | 53.00 B         |                
-------------------------+----------+---------------------------+------------------------------------+-----------------+----------------
                                                                                                       TOTAL OBJECTS:  |       3        
                                                                                                     ------------------+----------------

Listing all objects in the picture directory in the bucket1 bucket recursively

./coscli ls cos://bucket1/picture/ -r
If there are subpaths at the level of the query path, recursive listing will scan all subpaths and return all files under the level of the query path. Below is an example:

         KEY                  |   TYPE   |       LAST MODIFIED       |                ETAG                |      SIZE       | RESTORESTATUS  
------------------------------+----------+---------------------------+------------------------------------+-----------------+----------------
 picture/subfolder            | DIR      |                           |                                    |                 |                
 picture/subfolder/pic2.png   | STANDARD | 2024-06-05T15:03:58+08:00 | "bd5a4bd7248e7dfdb796383bee60470b" | 53.00 B         |                
------------------------------+----------+---------------------------+------------------------------------+-----------------+----------------
                                                                                                       TOTAL OBJECTS:  |       3        
                                                                                                     ------------------+----------------

Listing all MP4 objects in the bucket1 bucket recursively

./coscli ls cos://bucket1 -r --include ".*\\.mp4$"

Listing all non-MP4 objects in the bucket1 bucket recursively

./coscli ls cos://bucket1 -r --exclude ".*\\.mp4$"

Listing all non-JPG objects prefixed with test in the picture directory in the bucket1 bucket

./coscli ls cos://bucket1/picture -r --include "^picture/test.*" --exclude ".*\\.jpg$"

List Historical Versions

List All Earlier Versions in bucket1

./coscli ls cos://bucket1/ -r --all-versions
If there are subpaths at the level where the query path is located, recursive listing will scan all subpaths and return all historical versions of all files under the level of the query path. An example is as follows:
               KEY              |   TYPE   |          VERSIONID          | ISLATEST | DELETE MARKER |       LAST MODIFIED       |                ETAG                |  SIZE    
--------------------------------+----------+-----------------------------+----------+---------------+---------------------------+------------------------------------+----------
  cmd/cmd/abort.go              | STANDARD | MTg0NDUwMDM1MjIxMDM3MDI1MDM | false    | false         | 2025-02-26T14:33:25+08:00 | "c9bfc40db6669e9a7aee03abcd8b66e8" | 1.89 KB  
  cmd/cmd/abort_test.go         | STANDARD | MTg0NDUwMDM1MjIxMDM3MjgxODI | false    | false         | 2025-02-26T14:33:25+08:00 | "52166b1c60e4089a4652546c0350d2c7" | 4.89 KB  
  cmd/cmd/bucket_tagging.go     | STANDARD | MTg0NDUwMDM1MjIxMDM3MjY3MDI | false    | false         | 2025-02-26T14:33:25+08:00 | "edad62e08bf65a5bff81304e2b40ac1a" | 3.82 KB  
  cmd/cmd/bucket_versioning.go  | STANDARD | MTg0NDUwMDM1MjIxMDM2MTkzMzU | false    | false         | 2025-02-26T14:33:25+08:00 | "50a6b0e2e218c437ccdabe2c762aaef1" | 1.86 KB  
  cmd/cmd/buket_tagging_test.go | STANDARD | MTg0NDUwMDM1MjIxMDM2MTY4MDc | false    | false         | 2025-02-26T14:33:25+08:00 | "cd11257b22c9816df105da15f3ceb70f" | 8.23 KB  
  cmd/cmd/abort.go              |          | MTg0NDUwMDM1MjIwNjcyNTcxMDA | true     | true          | 2025-02-26T14:34:02+08:00 |                                    |          
  cmd/cmd/abort_test.go         |          | MTg0NDUwMDM1MjIwNjcxNzE5NDY | true     | true          | 2025-02-26T14:34:02+08:00 |                                    |          
  cmd/cmd/bucket_tagging.go     |          | MTg0NDUwMDM1MjIwNjcyNjczNzI | true     | true          | 2025-02-26T14:34:02+08:00 |                                    |          
  cmd/cmd/bucket_versioning.go  |          | MTg0NDUwMDM1MjIwNjY3ODc4NzM | true     | true          | 2025-02-26T14:34:02+08:00 |                                    |          
  cmd/cmd/buket_tagging_test.go |          | MTg0NDUwMDM1MjIwNjY3ODYyMDI | true     | true          | 2025-02-26T14:34:02+08:00 |                                    |          
--------------------------------+----------+-----------------------------+----------+---------------+---------------------------+------------------------------------+----------
                                                                                                                                            TOTAL OBJECTS:           |   10     
                                                                                                                                -------------------------------------+----------

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback