List files in a given folder.

Using the file naming convention that / separates folder names from their contents, returns a list of the files and folders in a given folder. If no folder name is given, lists all files at the top level.

The --long option produces very wide multi-column output showing the upload date/time, file size, file id, whether it is an uploaded file or the hiding of a file, and the file name. Folders don’t really exist in B2, so folders are shown with - in each of the fields other than the name.

The --json option produces machine-readable output similar to the server api response format.

The --replication option adds replication status

The --versions option selects all versions of each file, not just the most recent.

The --recursive option will descend into folders, and will select only files, not folders.

The --with-wildcard option will allow using *, ? and `[]` characters in folderName as a greedy wildcard, single character wildcard and range of characters. It requires the --recursive option. Remember to quote folderName to avoid shell expansion.

The –include and –exclude flags can be used to filter the files returned from the server using wildcards. You can specify multiple –include and –exclude filters. The order of filters matters. The last matching filter decides whether a file is included or excluded. If the given list of filters contains only INCLUDE filters, then it is assumed that all files are excluded by default.



Note the use of quotes, to ensure that special characters are not expanded by the shell.

List csv and tsv files (in any directory, in the whole bucket):

b2 ls --recursive --with-wildcard "b2://bucketName/*.[ct]sv"

List all info.txt files from directories named b?, where ? is any character:

b2 ls --recursive --with-wildcard "b2://bucketName/b?/info.txt"

List all pdf files from directories b0 to b9 (including sub-directories):

b2 ls --recursive --with-wildcard "b2://bucketName/b[0-9]/*.pdf"

List all buckets:

b2 ls

Requires capability:

  • listFiles

  • listBuckets (if bucket name is not provided)

b2 ls [-h] [--long] [--json] [--replication] [--versions] [-r]
      [--with-wildcard] [--include FILTERS] [--exclude FILTERS]

Positional Arguments


B2 URI pointing to a bucket, directory, file or all buckets. e.g. b2://yourBucket, b2://yourBucket/file.txt, b2://yourBucket/folderName/, b2id://fileId, or b2://

Named Arguments


Default: False


Default: False


Default: False


Default: False

-r, --recursive

Default: False


Default: False


Default: []


Default: []