How to use the ls command to list account-level resources - Object Storage Service

Use the ls command to list information about your buckets, objects, and multipart upload parts. This is useful for querying and managing your Object Storage Service (OSS) resources, such as finding and deleting large files to free up storage space.

Prerequisites

You must have the following Resource Access Management (RAM) permissions to perform list operations:

List buckets: oss:ListBuckets
List objects: oss:ListObjects
List object versions: oss:ListObjectVersions
List parts: oss:ListParts and oss:ListMultipartUploads

For more information, see Attach a custom policy to a RAM user.

Syntax

ossutil ls [oss://bucket[/prefix]] [options]

Option	Type	Description
--all-versions	/	Lists all versions of objects.
-d, --dirs	/	Lists only the top-level files and subdirectories in the specified directory, not recursively.
--encoding-type	string	Specifies the encoding type for object names or filenames. Valid value: `url`.
--end-with	string	Lists only objects whose names are lexicographically less than or equal to the specified value.
--exclude	stringArray	Excludes files and paths that match the specified rules.
--exclude-from	stringArray	Reads exclude rules from the specified rule file.
--files-from	stringArray	Reads the list of source filenames from a file. Empty lines and lines starting with a hash (#) are ignored.
--files-from-raw	stringArray	Reads the list of source filenames from a file.
--filter	stringArray	Specifies one or more filter rules for file paths or names.
--filter-from	stringArray	Reads filter rules from the specified rule file.
-f, --force	/	Forces the operation and suppresses confirmation prompts.
--include	stringArray	Includes only files and paths that match the specified rules.
--include-from	stringArray	Reads include rules from the specified rule file.
--limited-num	int	Specifies the maximum number of results to return.
--list-objects	/	Lists objects by using the `ListObjects` (GetBucket) API operation.
--max-size	SizeSuffix	Lists only objects no larger than the specified size. The default unit is bytes. You can use a suffix, such as B, K, M, G, T, or P. Note that 1 K represents one kibibyte (1,024 bytes).
--metadata-exclude	stringArray	Specifies exclude rules for object metadata.
--metadata-filter	stringArray	Specifies filter rules for object metadata.
--metadata-filter-from	stringArray	Reads object metadata filter rules from the specified rule file.
--metadata-include	stringArray	Specifies include rules for object metadata.
--min-age	Duration	Lists only files older than the specified duration. The default unit is seconds. You can also use a unit suffix, such as `h` for hours. Note For example, `--min-age 1h` lists only files last modified more than one hour ago.
--max-age	Duration	Lists only files modified within the specified duration. The default unit is seconds. You can also use a unit suffix, such as `h` for hours. Note For example, `--max-age 1h` lists only files last modified within the last hour.
--min-mtime	Time	Lists only files modified after the specified time. The time must be in UTC format, such as 2006-01-02T15:04:05Z. Note For example, `--min-mtime "2006-01-02T15:04:05Z"` lists only files last modified after 15:04:05 on January 2, 2006.
--max-mtime	Time	Lists only files modified before the specified time. The time must be in UTC format, such as 2006-01-02T15:04:05Z.
--min-size	SizeSuffix	Lists only objects no smaller than the specified size. The default unit is bytes. You can use a suffix, such as B, K, M, G, T, or P. Note that 1 K (KiB) is equal to 1,024 bytes.
--multipart	/	Lists incomplete multipart upload tasks.
--page-size	int	Specifies the maximum number of objects to return per page in a batch operation. The default value is 1,000. Valid values range from 1 to 1,000.
-r, --recursive	/	Recursively lists all matching objects. Without this option, the command lists only top-level items in the specified path.
--request-payer	string	Specifies the payer for the request. If the bucket uses the Requester Pays mode, set this option to `requester`.
--short-format	/	Displays output in short format. Long format is used by default.
--start-after	string	Lists only objects whose names are lexicographically greater than the specified value.
--resource-group-id	string	Specifies the ID of the resource group.

Note

For more information, see Command-line options.

Examples

List all buckets.
```
ossutil ls
```
List all objects in the bucket named examplebucket.
```
ossutil ls oss://examplebucket
```
List all objects with the dir/ prefix in the bucket named examplebucket.
```
ossutil ls oss://examplebucket/dir
```
List only the top-level objects and subdirectories in the dir/ directory of the bucket named examplebucket.
```
ossutil ls oss://examplebucket/dir -d
```
List the first 100 objects with the dir/ prefix in the bucket named examplebucket.
```
ossutil ls oss://examplebucket/dir --limited-num 100
```
List all .txt files within the dir1/ and dir2/ directories (including subdirectories) in the bucket named examplebucket.
```
ossutil ls oss://examplebucket/ --include "/dir1/**.txt" --include "/dir2/**.txt"
```
List all files created within the last three days in the dir1/ and dir2/ directories (including subdirectories) in the bucket named examplebucket.
```
ossutil ls oss://examplebucket --include "/dir1/**" --include "/dir2/**" --max-age 3d
```
List all buckets and format the output in JSON.
```
ossutil ls --output-format json
```