- NAME
-
- gcloud storage ls - list Cloud Storage buckets and objects
- SYNOPSIS
-
-
gcloud storage ls
[PATH
…] [--additional-headers
=HEADER
=VALUE
] [--all-versions
,-a
] [--buckets
,-b
] [--etag
,-e
] [--exhaustive
] [--fetch-encrypted-object-hashes
] [--format
=FORMAT
] [--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 …
]
-
- DESCRIPTION
- List your Cloud Storage buckets in a project and objects in a bucket. This command treats forward slashes in object names as directories. See below for examples of how to use wildcards to get the listing behavior you want.
- EXAMPLES
-
The following command lists the buckets in the default project:
gcloud storage ls
The following command lists the buckets in the specified project:
gcloud storage ls --project=my-project
The following command lists the contents of a bucket:
gcloud 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
objects that begin with.txt
and that are stored in buckets in your project that begin withlog
:my-b
gcloud 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
objects in a bucket..txt
gcloud 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 matchgs://my-bucket/dir/log.txt
:gcloud 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 asgs://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 storage ls --recursive gs://bucket
Recursive listings are similar to
**
except recursive listings include line breaks and header formatting for each subdirectory. - POSITIONAL ARGUMENTS
-
- [
PATH
…] - The path of objects and directories to list. The path must begin with gs:// and is allowed to contain wildcard characters.
- [
- FLAGS
-
--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 defaultstorage/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.
--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 objects only. Excludes live and noncurrent objects.
-
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.
- ENCRYPTION FLAGS
-
--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.
- GCLOUD WIDE FLAGS
-
These flags are available to all commands:
--access-token-file
,--account
,--billing-project
,--configuration
,--flags-file
,--flatten
,--format
,--help
,--impersonate-service-account
,--log-http
,--project
,--quiet
,--trace-token
,--user-output-enabled
,--verbosity
.Run
$ gcloud help
for details. - NOTES
-
This variant is also available:
gcloud alpha storage ls
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-06-25 UTC.
[{
"type": "thumb-down",
"id": "hardToUnderstand",
"label":"Hard to understand"
},{
"type": "thumb-down",
"id": "incorrectInformationOrSampleCode",
"label":"Incorrect information or sample code"
},{
"type": "thumb-down",
"id": "missingTheInformationSamplesINeed",
"label":"Missing the information/samples I need"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]
{
"lastModified": "Last updated 2024-06-25 UTC.",
"confidential": False
}