The command-line tool that gives easy access to all of the capabilities of B2 Cloud Storage
Clone or download
bwbeach Merge pull request #524 from Backblaze/api_v2
Update command-line tool to use v2 of the B2 APIs
Latest commit 307be93 Oct 17, 2018
Failed to load latest commit information.
b2 Merge pull request #524 from Backblaze/api_v2 Oct 17, 2018
ci/appveyor Attempt at workaround for problem installing pip for 2.6.6. Oct 26, 2017
contrib Use `_have` instead of `have` Aug 19, 2018
doc Make license uniform, make travis enforce it Aug 1, 2018
test Merge pull request #524 from Backblaze/api_v2 Oct 17, 2018
.gitignore Implemented #404. Mar 16, 2018
.travis.yml Make license uniform, make travis enforce it Aug 1, 2018
LICENSE Update license text and include link to web site. Nov 16, 2015 Include LICENSE file in the source tarball. Fixes #433 Mar 31, 2018
Makefile Add format target that runs yapf. Mar 21, 2018 rename option to --excludeAllSymlinks, add unit tests Sep 25, 2018 Add instructions on updating packages, including setuptools. Aug 13, 2018
appveyor.yml It turns out that 3.7 was release just a week ago, and the test envir… Jul 4, 2018 Add a help message to Aug 4, 2018
requirements-setup.txt Do not depend on twine in 2.6. Sep 26, 2018
requirements-test.txt Fix 2.6 build by not installing pyflakes. Jul 4, 2018
requirements.txt Do not use arrow 0.12.1 which breaks compatibility with 2.6 Feb 14, 2018 Add pretty banner after all unit tests pass Jul 5, 2016
setup.cfg Let flake8 know about line length 100 too. Mar 17, 2018 Version 1.3.7 for dev Aug 21, 2018 make reporter.symlink_skipped a noop Sep 27, 2018

B2 Command Line Tool Travis CI License python versions PyPI version

The command-line tool that gives easy access to all of the capabilities of B2 Cloud Storage.

This program provides command-line access to the B2 service.

Version 1.3.7


This tool can be installed with:

pip install b2

If you see a message saying that the six library cannot be installed, which happens if you're installing with the system python on OS X El Capitan, try this:

pip install --ignore-installed b2


b2 authorize-account [<accountIdOrKeyId>] [<applicationKey>]
b2 cancel-all-unfinished-large-files <bucketName>
b2 cancel-large-file <fileId>
b2 clear-account
b2 create-bucket [--bucketInfo <json>] [--corsRules <json>] [--lifecycleRules <json>] <bucketName> [allPublic | allPrivate]
b2 create-key [--duration <validDurationSeconds>] [--bucket <bucketName>] [--namePrefix <namePrefix>] <keyName> <capabilities>
b2 delete-bucket <bucketName>
b2 delete-file-version [<fileName>] <fileId>
b2 delete-key <applicationKeyId>
b2 download-file-by-id [--noProgress] <fileId> <localFileName>
b2 download-file-by-name [--noProgress] <bucketName> <fileName> <localFileName>
b2 get-account-info
b2 get-bucket [--showSize] <bucketName>
b2 get-download-auth [--prefix <fileNamePrefix>] [--duration <durationInSeconds>] <bucketName>
b2 get-download-url-with-auth [--duration <durationInSeconds>] <bucketName> <fileName>
b2 get-file-info <fileId>
b2 help [commandName]
b2 hide-file <bucketName> <fileName>
b2 list-buckets
b2 list-file-names <bucketName> [<startFileName>] [<maxToShow>]
b2 list-file-versions <bucketName> [<startFileName>] [<startFileId>] [<maxToShow>]
b2 list-keys
b2 list-parts <largeFileId>
b2 list-unfinished-large-files <bucketName>
b2 ls [--long] [--versions] [--recursive] <bucketName> [<folderName>]
b2 make-url <fileId>
b2 sync [--delete] [--keepDays N] [--skipNewer] [--replaceNewer] \
    [--compareVersions <option>] [--compareThreshold N] \
    [--threads N] [--noProgress] [--dryRun ] [--allowEmptySource ] \
    [--excludeRegex <regex> [--includeRegex <regex>]] \
    [--excludeDirRegex <regex>] \
    [--excludeAllSymlinks ] \
    <source> <destination>
b2 update-bucket [--bucketInfo <json>] [--corsRules <json>] [--lifecycleRules <json>] <bucketName> [allPublic | allPrivate]
b2 upload-file [--sha1 <sha1sum>] [--contentType <contentType>] \
    [--info <key>=<value>]* [--minPartSize N] \
    [--noProgress] [--threads N] <bucketName> <localFilePath> <b2FileName>
b2 version

The environment variable B2_ACCOUNT_INFO specifies the sqlite file to use for caching authentication information. The default file to use is: ~/.b2_account_info

For more details on one command: b2 help

When authorizing with application keys, this tool requires that the key have the 'listBuckets' capability so that it can take the bucket names you provide on the command line and translate them into bucket IDs for the B2 Storage service. Each different command may required additional capabilities. You can find the details for each command in the help for that command.

Parallelism and the --threads parameter

Users with high performance networks, or file sets with very small files, may benefit from increased parallelism. Experiment with using the --threads parameter with small values to determine if there are benefits.

Note that using multiple threads will usually be detrimental to the other users on your network.


bash completion

You can find a bash completion script in the contrib directory. See this for installation instructions.

detailed logs

Verbose logs to stdout can be enabled with the --verbose flag.

A hidden flag --debugLogs can be used to enable logging to a b2_cli.log file (with log rotation at midnight) in current working directory. Please take care to not launch the tool from the directory that you are syncing, or the logs will get synced to the remote server (unless that is really what you want to do).

For advanced users, a hidden option --logConfig <filename.ini> can be used to enable logging in a user-defined format and verbosity. An example log configuration can be found here.

Release History

1.3.6 (August 21, 2018)

Bug fixes:

  • Fix auto-reauthorize for application keys.
  • Fix problem with bash auto-completion module.
  • Fix (hopefully) markdown display in PyPI.

1.3.4 (August 10, 2018)

Bug fixes:

  • Better documentation for authorize-account command.
  • Fix error reporting when using application keys
  • Fix auth issues with bucket-restricted application keys.

1.3.2 (July 28, 2018)

Bug fixes:

  • Tests fixed for Python 3.7
  • Add documentation about what capabilites are required for different commands.
  • Better error messages for authorization problems with application keys.

1.3.0 (July 20, 2018)

New features:

  • Support for application keys.
  • Support for Python 3.6
  • Drop support for Python 3.3 (setuptools no longer supports 3.3)

Bug fixes:

  • Fix content type so markdown displays properly in PyPI
  • The testing package is called test, not tests

Internal upgrades:

  • Faster and more complete integration tests

1.2.0 (July 6, 2018)

New features:

  • New --recursive option for ls
  • New --showSize option for get-bucket
  • New --excludeDirRegex option for sync

And some bug fixes:

  • Include LICENSE file in the source tarball. Fixes #433
  • Test suite now runs as root (fixes #427)
  • Validate file names before trying to upload
  • Fix scaling problems when syncing large numbers of files
  • Prefix Windows paths during sync to handle long paths (fixes #265)
  • Check if file to be synced is still accessible before syncing (fixes #397)

1.1.0 (November 30, 2017)

Just one change in this release:

  • Add support for CORS rules in create-bucket and update-bucket. get-bucket will display CORS rules.

1.0.0 (November 9, 2017)

This is the same code as 0.7.4, with one incompatible change:

  • Require --allowEmptySource to sync from empty directory, to help avoid accidental deletion of all files.

0.7.4 (November 9, 2017)

New features:

  • More efficient uploads by sending SHA1 checksum at the end.

Includes a number of bug fixes:

  • File modification times are set correctly when downloading.
  • Fix an off-by-one issue when downloading a range of a file (affects library, but not CLI).
  • Better handling of some errors from the B2 service.

Developer Info

We encourage outside contributors to perform changes on our codebase. Many such changes have been merged already. In order to make it easier to contribute, core developers of this project:

  • provide guidance (through the issue reporting system)
  • provide tool assisted code review (through the Pull Request system)
  • maintain a set of integration tests (run with a production cloud)
  • maintain a set of (well over a hundred) unit tests
  • automatically run unit tests on 14 versions of python (including osx, Jython and pypy)
  • format the code automatically using yapf
  • use static code analysis to find subtle/potential issues with maintainability
  • maintain other Continous Integration tools (coverage tracker)

You'll need to some Python packages installed. To get all the latest things:

  • pip install --upgrade --upgrade-strategy eager -r requirements.txt -r requirements-test.txt -r requirements-setup.txt

There is a Makefile with a rule to run the unit tests using the currently active Python:

make setup
make test

will install the required packages, then run the unit tests.

To test in multiple python virtual environments, set the enviroment variable PYTHON_VIRTUAL_ENVS to be a space-separated list of their root directories. When set, the makefile will run the unit tests in each of the environments.

Before checking in, use the script to check code formatting, run unit tests, run integration tests etc.

The integration tests need a file in your home directory called .b2_auth that contains two lines with nothing on them but your account ID and application key:


We marked the places in the code which are significantly less intuitive than others in a special way. To find them occurrences, use git grep '*magic*'.