gcloud alpha storage ls

gcloud alpha storage ls - list Cloud Storage buckets and objects

gcloud alpha storage ls [PATH …] [--additional-headers=HEADER=VALUE] [--all-versions, -a] [--buckets, -b] [--etag, -e] [--exhaustive] [--fetch-encrypted-object-hashes] [--format=FORMAT] [--metadata-filter=METADATA_FILTER] [--next-page-token=NEXT_PAGE_TOKEN] [--read-paths-from-stdin, -I] [--readable-sizes] [--recursive, -R, -r] [--soft-deleted] [--full, -L     | --json, -j     | --long, -l] [--decryption-keys=[DECRYPTION_KEY,…]] [GCLOUD_WIDE_FLAG …]

gcloud alpha storage ls

The following command lists the buckets in the specified project:

gcloud alpha storage ls --project=my-project

The following command lists the contents of a bucket:

gcloud alpha storage ls gs://my-bucket

You can use wildcards to match multiple paths (including multiple buckets). Bucket wildcards are expanded to match only buckets contained in your current project. The following command matches .txt objects that begin with log and that are stored in buckets in your project that begin with my-b:

gcloud alpha storage ls gs://my-b*/log*.txt

You can use double-star wildcards to match zero or more directory levels in a path. The following command matches all .txt objects in a bucket.

gcloud alpha storage ls gs://my-bucket/**/*.txt

The wildcard ** retrieves a flat list of objects in a single API call and does not match prefixes. The following command would not match gs://my-bucket/dir/log.txt:

gcloud alpha storage ls gs://my-bucket/**/dir

Double-star expansion also can not be combined with other expressions in a given path segment and operates as a single star in that context. For example, the command gs://my-bucket/dir**/log.txt is treated as gs://my-bucket/dir*/log.txt. To get the recursive behavior, the command should instead be written the following way:

gs://my-bucket/dir*/**/log.txt

The following command lists all items recursively with formatting by using --recursive:

gcloud alpha storage ls --recursive gs://bucket

Recursive listings are similar to ** except recursive listings include line breaks and header formatting for each subdirectory.

The following command filters objects based on specified filter while listing. Note that the flag is only supported for Google Cloud Storage URLs and only applies to objects. This means that directories or buckets will still be listed even if they do not contain objects that match the filter.

gcloud alpha storage ls gs://my-bucket --metadata-filter='contexts."foo"="bar"'

[PATH …]

The path of objects and directories to list. The path must begin with gs:// and is allowed to contain wildcard characters.

--additional-headers=HEADER=VALUE

Includes arbitrary headers in storage API calls. Accepts a comma separated list of key=value pairs, e.g. header1=value1,header2=value2. Overrides the default storage/additional_headers property value for this command invocation.

--all-versions, -a

Include noncurrent object versions in the listing. This flag is typically only useful for buckets with object versioning enabled. If combined with the --long option, the metageneration for each listed object is also included.

--buckets, -b

When given a bucket URL, only return buckets. Useful for avoiding the rule that prints the top-level objects of buckets matching a query. Typically used in combination with --full to get the full metadata of buckets.

--etag, -e

Include ETag metadata in listings that use the --long flag.

--exhaustive

For features like soft delete, the API may return an empty list. If present, continue querying. This may incur costs from repeated LIST calls and may not return any additional objects.

--fetch-encrypted-object-hashes

API requests to the LIST endpoint do not fetch the hashes for encrypted objects by default. If this flag is set, a GET request is sent for each encrypted object in order to fetch hashes. This can significantly increase the cost of the command.

--format=FORMAT

Use "gsutil" to get the style of the older gsutil CLI. (e.g. "--format=gsutil"). Other format values (e.g. "json") do not work. See different ls flags and commands for alternative formatting.

--metadata-filter=METADATA_FILTER

Server side filtering for objects. Works only for Google Cloud Storage URLs. The filter only works for objects, and not directories or buckets, which means commands like storage ls and storage du will still list directories or buckets even if they do not contain any objects matching the filter. See https://cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax for more details.

--next-page-token=NEXT_PAGE_TOKEN

Page token for resuming LIST calls.

--read-paths-from-stdin, -I

Read the list of URLs from stdin.

--readable-sizes

When used with --long, print object sizes in human readable format, such as 1 KiB, 234 MiB, or 2 GiB.

--recursive, -R, -r

Recursively list the contents of any directories that match the path expression.

--soft-deleted

Displays soft-deleted resources only. For objects, it will exclude live and noncurrent ones.

At most one of these can be specified:

--full, -L

List all available metadata about items in rows.

--json, -j

List all available metadata about items as a JSON dump.

--long, -l

For objects only. List size in bytes, creation time, and URL.

--decryption-keys=[DECRYPTION_KEY,…]

A comma-separated list of customer-supplied encryption keys (RFC 4648 section 4 base64-encoded AES256 strings) that will be used to decrypt Cloud Storage objects. Data encrypted with a customer-managed encryption key (CMEK) is decrypted automatically, so CMEKs do not need to be listed here.