List your storage buckets and objects in your buckets. This command treats
forward slashes in object names as directories.
EXAMPLES
The following command lists the contents of a bucket:
gdcloud storage ls s3://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":
gdcloud storage ls s3://my-b*/log*.txt
The following wildcards are valid and match only within the current
directory:
*: Matches zero or more characters
?: Matches zero or one characters
[]: Matches a character range (ex. [a-z] or [0-9])
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.
gdcloud storage ls s3://my-bucket/**/*.txt
Double-star expansion can not be combined with other expressions in a given
path segment and operates as a single star in that context. For example:
s3://my-bucket/dir**/log.txt
is treated as:
s3://my-bucket/dir*/log.txt
and instead should be written as:
s3://my-bucket/dir*/**/log.txt
to get the recursive behavior.
The following command lists all items recursively with formatting by using
--recursive:
gdcloud storage ls --recursive s3://bucket
Recursive listings are similar to ** except recursive listings include
line breaks and header formatting for each subdirectory.
OPTIONAL FLAGS
-a, --all-versions Include non-current 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.
-b, --buckets 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.
-L, --full List all available metadata about items in rows.
-j, --json List all available metadata about items as a JSON dump.
--log-http Log all HTTP server requests and responses to stderr.
-l, --long List objects only. List size in bytes, creation time, and URL.
-r, --recursive Recursively list the contents of any directories that match the path expression.
--verbosity string Override the default verbosity for this command. VERBOSITY must be one of:
debug, info, warning, error, critical, none. (default "warning")
GDCLOUD WIDE FLAGS
These flags are available to all commands: --configuration, --format, --help, --project, --quiet.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003egdcloud storage ls\u003c/code\u003e command lists storage buckets and objects, treating forward slashes in object names as directories.\u003c/p\u003e\n"],["\u003cp\u003eWildcards like \u003ccode\u003e*\u003c/code\u003e, \u003ccode\u003e?\u003c/code\u003e, and \u003ccode\u003e[]\u003c/code\u003e can be used to match multiple paths within buckets, and \u003ccode\u003e**\u003c/code\u003e matches zero or more directory levels.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e--recursive\u003c/code\u003e flag lists all items recursively, including line breaks and header formatting for each subdirectory.\u003c/p\u003e\n"],["\u003cp\u003eOptional flags such as \u003ccode\u003e--all-versions\u003c/code\u003e, \u003ccode\u003e--buckets\u003c/code\u003e, \u003ccode\u003e--full\u003c/code\u003e, \u003ccode\u003e--json\u003c/code\u003e, and \u003ccode\u003e--long\u003c/code\u003e offer different levels of detail and filtering for the listed items.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003egdcloud storage ls\u003c/code\u003e also accepts globally available flags like \u003ccode\u003e--configuration\u003c/code\u003e, \u003ccode\u003e--format\u003c/code\u003e, and \u003ccode\u003e--project\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# gdcloud storage ls\n\nNAME\n----\n\ngdcloud storage ls - List storage buckets and objects\n\nSYNOPSIS\n--------\n\n gdcloud storage ls [PATH ...]\n [--all-versions, -a]\n [--buckets, -b]\n [--readable-sizes]\n [--recursive, -r]\n [--full, -L | --json, -j | --long, -l]\n [--format=FORMAT]\n [--log-http]\n [--verbosity=VERBOSITY] [flags]\n\nDESCRIPTION\n-----------\n\nList your storage buckets and objects in your buckets. This command treats\nforward slashes in object names as directories.\n\n### EXAMPLES\n\n The following command lists the contents of a bucket:\n\n gdcloud storage ls s3://my-bucket\n\n You can use wildcards to match multiple paths, including multiple buckets.\n Bucket wildcards are expanded to match only buckets contained in your\n current project. The following command matches .txt objects that begin with\n \"log\" and that are stored in buckets in your project that begin with \"my-b\":\n\n gdcloud storage ls s3://my-b*/log*.txt\n\n The following wildcards are valid and match only within the current\n directory:\n\n *: Matches zero or more characters\n ?: Matches zero or one characters\n []: Matches a character range (ex. [a-z] or [0-9])\n\n You can use double-star wildcards to match zero or more directory levels in\n a path. The following command matches all .txt objects in a bucket.\n\n gdcloud storage ls s3://my-bucket/**/*.txt\n\n Double-star expansion can not be combined with other expressions in a given\n path segment and operates as a single star in that context. For example:\n\n s3://my-bucket/dir**/log.txt\n\n is treated as:\n\n s3://my-bucket/dir*/log.txt\n\n and instead should be written as:\n\n s3://my-bucket/dir*/**/log.txt\n\n to get the recursive behavior.\n\n The following command lists all items recursively with formatting by using\n --recursive:\n\n gdcloud storage ls --recursive s3://bucket\n\n Recursive listings are similar to ** except recursive listings include\n line breaks and header formatting for each subdirectory.\n\n### OPTIONAL FLAGS\n\n -a, --all-versions Include non-current object versions in the listing. This flag is\n typically only useful for buckets with object versioning enabled. If\n combined with the --long option, the metageneration for each listed\n object is also included.\n -b, --buckets When given a bucket URL, only return buckets. Useful for avoiding the\n rule that prints the top-level objects of buckets matching a query.\n Typically used in combination with --full to get the full metadata of\n buckets.\n -L, --full List all available metadata about items in rows.\n -j, --json List all available metadata about items as a JSON dump.\n --log-http Log all HTTP server requests and responses to stderr.\n -l, --long List objects only. List size in bytes, creation time, and URL.\n -r, --recursive Recursively list the contents of any directories that match the path expression.\n --verbosity string Override the default verbosity for this command. VERBOSITY must be one of:\n debug, info, warning, error, critical, none. (default \"warning\")\n\n### GDCLOUD WIDE FLAGS\n\nThese flags are available to all commands: `--configuration`, `--format`, `--help`, `--project`, `--quiet`.\n\nFor more information, see the [gdcloud CLI reference overview](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-reference/gdcloud) page."]]