.TH "GCLOUD_ALPHA_STORAGE_LS" 1



.SH "NAME"
.HP
gcloud alpha storage ls \- list Cloud Storage buckets and objects



.SH "SYNOPSIS"
.HP
\f5gcloud alpha storage ls\fR [\fIPATH\fR\ ...] [\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR] [\fB\-\-all\-versions\fR,\ \fB\-a\fR] [\fB\-\-buckets\fR,\ \fB\-b\fR] [\fB\-\-etag\fR,\ \fB\-e\fR] [\fB\-\-exhaustive\fR] [\fB\-\-fetch\-encrypted\-object\-hashes\fR] [\fB\-\-format\fR=\fIFORMAT\fR] [\fB\-\-metadata\-filter\fR=\fIMETADATA_FILTER\fR] [\fB\-\-next\-page\-token\fR=\fINEXT_PAGE_TOKEN\fR] [\fB\-\-read\-paths\-from\-stdin\fR,\ \fB\-I\fR] [\fB\-\-readable\-sizes\fR] [\fB\-\-recursive\fR,\ \fB\-R\fR,\ \fB\-r\fR] [\fB\-\-soft\-deleted\fR] [\fB\-\-full\fR,\ \fB\-L\fR\ |\ \fB\-\-json\fR,\ \fB\-j\fR\ |\ \fB\-\-long\fR,\ \fB\-l\fR] [\fB\-\-decryption\-keys\fR=[\fIDECRYPTION_KEY\fR,...]] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(ALPHA)\fR 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.



.SH "EXAMPLES"

The following command lists the buckets in the default project:

.RS 2m
$ gcloud alpha storage ls
.RE

The following command lists the buckets in the specified project:

.RS 2m
$ gcloud alpha storage ls \-\-project=my\-project
.RE

The following command lists the contents of a bucket:

.RS 2m
$ gcloud alpha storage ls gs://my\-bucket
.RE

You can use wildcards (https://cloud.google.com/storage/docs/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 \f5\fI.txt\fR\fR objects that begin with \f5\fIlog\fR\fR and that are
stored in buckets in your project that begin with \f5\fImy\-b\fR\fR:

.RS 2m
$ gcloud alpha storage ls gs://my\-b*/log*.txt
.RE

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

.RS 2m
$ gcloud alpha storage ls gs://my\-bucket/**/*.txt
.RE

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

.RS 2m
$ gcloud alpha storage ls gs://my\-bucket/**/dir
.RE

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 \f5gs://my\-bucket/dir**/log.txt\fR is treated as
\f5gs://my\-bucket/dir*/log.txt\fR. To get the recursive behavior, the command
should instead be written the following way:

.RS 2m
gs://my\-bucket/dir*/**/log.txt
.RE

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

.RS 2m
$ gcloud alpha storage ls \-\-recursive gs://bucket
.RE

Recursive listings are similar to \f5**\fR 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.

.RS 2m
$ gcloud alpha storage ls gs://my\-bucket \e
    \-\-metadata\-filter='contexts."foo"="bar"'
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
[\fIPATH\fR ...]

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


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR

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

.TP 2m
\fB\-\-all\-versions\fR, \fB\-a\fR

Include noncurrent object versions in the listing. This flag is typically only
useful for buckets with object versioning
(https://cloud.google.com/storage/docs/object\-versioning) enabled. If combined
with the \f5\-\-long\fR option, the metageneration for each listed object is
also included.

.TP 2m
\fB\-\-buckets\fR, \fB\-b\fR

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 \f5\-\-full\fR to get the full metadata of buckets.

.TP 2m
\fB\-\-etag\fR, \fB\-e\fR

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

.TP 2m
\fB\-\-exhaustive\fR

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.

.TP 2m
\fB\-\-fetch\-encrypted\-object\-hashes\fR

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.

.TP 2m
\fB\-\-format\fR=\fIFORMAT\fR

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.

.TP 2m
\fB\-\-metadata\-filter\fR=\fIMETADATA_FILTER\fR

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 \f5storage ls\fR and \f5storage du\fR 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.

.TP 2m
\fB\-\-next\-page\-token\fR=\fINEXT_PAGE_TOKEN\fR

Page token for resuming LIST calls.

.TP 2m
\fB\-\-read\-paths\-from\-stdin\fR, \fB\-I\fR

Read the list of URLs from stdin.

.TP 2m
\fB\-\-readable\-sizes\fR

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

.TP 2m
\fB\-\-recursive\fR, \fB\-R\fR, \fB\-r\fR

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

.TP 2m
\fB\-\-soft\-deleted\fR

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

.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-full\fR, \fB\-L\fR

List all available metadata about items in rows.

.TP 2m
\fB\-\-json\fR, \fB\-j\fR

List all available metadata about items as a JSON dump.

.TP 2m
\fB\-\-long\fR, \fB\-l\fR

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


.RE
.RE
.sp

.SH "ENCRYPTION FLAGS"

.RS 2m
.TP 2m
\fB\-\-decryption\-keys\fR=[\fIDECRYPTION_KEY\fR,...]

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.


.RE
.sp

.SH "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 \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. This variant is also available:

.RS 2m
$ gcloud storage ls
.RE