gcloud-help/gcloud/storage/ls

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 (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 .txt objects that begin with log and that are
    stored in buckets in your project that begin with 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 .txt objects in a bucket.

        $ 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 match
    gs://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 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 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 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
        (https://cloud.google.com/storage/docs/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 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.

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