README.md
1# B2 Command Line Tool [](https://travis-ci.org/Backblaze/B2_Command_Line_Tool) [](https://pypi.python.org/pypi/b2) [](https://pypi.python.org/pypi/b2) [](https://pypi.python.org/pypi/b2)
2
3The command-line tool that gives easy access to all of the capabilities of B2 Cloud Storage.
4
5This program provides command-line access to the B2 service.
6
7Version 1.3.8
8
9# Installation
10
11This tool can be installed with:
12
13 pip install b2
14
15If you see a message saying that the `six` library cannot be installed, which
16happens if you're installing with the system python on OS X El Capitan, try
17this:
18
19 pip install --ignore-installed b2
20
21# Usage
22
23 b2 authorize-account [<accountIdOrKeyId>] [<applicationKey>]
24 b2 cancel-all-unfinished-large-files <bucketName>
25 b2 cancel-large-file <fileId>
26 b2 clear-account
27 b2 create-bucket [--bucketInfo <json>] [--corsRules <json>] [--lifecycleRules <json>] <bucketName> [allPublic | allPrivate]
28 b2 create-key [--duration <validDurationSeconds>] [--bucket <bucketName>] [--namePrefix <namePrefix>] <keyName> <capabilities>
29 b2 delete-bucket <bucketName>
30 b2 delete-file-version [<fileName>] <fileId>
31 b2 delete-key <applicationKeyId>
32 b2 download-file-by-id [--noProgress] <fileId> <localFileName>
33 b2 download-file-by-name [--noProgress] <bucketName> <fileName> <localFileName>
34 b2 get-account-info
35 b2 get-bucket [--showSize] <bucketName>
36 b2 get-download-auth [--prefix <fileNamePrefix>] [--duration <durationInSeconds>] <bucketName>
37 b2 get-download-url-with-auth [--duration <durationInSeconds>] <bucketName> <fileName>
38 b2 get-file-info <fileId>
39 b2 help [commandName]
40 b2 hide-file <bucketName> <fileName>
41 b2 list-buckets
42 b2 list-file-names <bucketName> [<startFileName>] [<maxToShow>]
43 b2 list-file-versions <bucketName> [<startFileName>] [<startFileId>] [<maxToShow>]
44 b2 list-keys
45 b2 list-parts <largeFileId>
46 b2 list-unfinished-large-files <bucketName>
47 b2 ls [--long] [--versions] [--recursive] <bucketName> [<folderName>]
48 b2 make-url <fileId>
49 b2 sync [--delete] [--keepDays N] [--skipNewer] [--replaceNewer] \
50 [--compareVersions <option>] [--compareThreshold N] \
51 [--threads N] [--noProgress] [--dryRun ] [--allowEmptySource ] \
52 [--excludeRegex <regex> [--includeRegex <regex>]] \
53 [--excludeDirRegex <regex>] \
54 [--excludeAllSymlinks ] \
55 <source> <destination>
56 b2 update-bucket [--bucketInfo <json>] [--corsRules <json>] [--lifecycleRules <json>] <bucketName> [allPublic | allPrivate]
57 b2 upload-file [--sha1 <sha1sum>] [--contentType <contentType>] \
58 [--info <key>=<value>]* [--minPartSize N] \
59 [--noProgress] [--threads N] <bucketName> <localFilePath> <b2FileName>
60 b2 version
61
62The environment variable B2_ACCOUNT_INFO specifies the sqlite
63file to use for caching authentication information.
64The default file to use is: ~/.b2_account_info
65
66For more details on one command: b2 help <command>
67
68When authorizing with application keys, this tool requires that the key
69have the 'listBuckets' capability so that it can take the bucket names
70you provide on the command line and translate them into bucket IDs for the
71B2 Storage service. Each different command may required additional
72capabilities. You can find the details for each command in the help for
73that command.
74
75## Parallelism and the --threads parameter
76
77Users with high performance networks, or file sets with very small files, may benefit from
78increased parallelism. Experiment with using the --threads parameter with small values to
79determine if there are benefits.
80
81Note that using multiple threads will usually be detrimental to the other users on your network.
82
83# Contrib
84
85## bash completion
86
87You can find a [bash completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion)
88script in the `contrib` directory. See [this](doc/bash_completion.md) for installation instructions.
89
90## detailed logs
91
92Verbose logs to stdout can be enabled with the `--verbose` flag.
93
94A 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).
95
96For 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](contrib/debug_logs.ini).
97
98# Release History
99
100## 1.3.8 (December 6, 2018)
101
102New features:
103
104* New `--excludeAllSymlinks` option for `sync`.
105* Faster downloading of large files using multiple threads and bigger buffers.
106
107Bug fixes:
108
109* Fixed doc for cancel-all-unfinished-large-files
110
111## 1.3.6 (August 21, 2018)
112
113Bug fixes:
114
115* Fix auto-reauthorize for application keys.
116* Fix problem with bash auto-completion module.
117* Fix (hopefully) markdown display in PyPI.
118
119## 1.3.4 (August 10, 2018)
120
121Bug fixes:
122
123* Better documentation for authorize-account command.
124* Fix error reporting when using application keys
125* Fix auth issues with bucket-restricted application keys.
126
127## 1.3.2 (July 28, 2018)
128
129Bug fixes:
130
131* Tests fixed for Python 3.7
132* Add documentation about what capabilites are required for different commands.
133* Better error messages for authorization problems with application keys.
134
135## 1.3.0 (July 20, 2018)
136
137New features:
138
139* Support for [application keys](https://www.backblaze.com/b2/docs/application_keys.html).
140* Support for Python 3.6
141* Drop support for Python 3.3 (`setuptools` no longer supports 3.3)
142
143Bug fixes:
144
145* Fix content type so markdown displays properly in PyPI
146* The testing package is called `test`, not `tests`
147
148Internal upgrades:
149
150* Faster and more complete integration tests
151
152## 1.2.0 (July 6, 2018)
153
154New features:
155
156* New `--recursive` option for ls
157* New `--showSize` option for get-bucket
158* New `--excludeDirRegex` option for sync
159
160And some bug fixes:
161
162* Include LICENSE file in the source tarball. Fixes #433
163* Test suite now runs as root (fixes #427)
164* Validate file names before trying to upload
165* Fix scaling problems when syncing large numbers of files
166* Prefix Windows paths during sync to handle long paths (fixes #265)
167* Check if file to be synced is still accessible before syncing (fixes #397)
168
169## 1.1.0 (November 30, 2017)
170
171Just one change in this release:
172
173* Add support for CORS rules in `create-bucket` and `update-bucket`. `get-bucket` will display CORS rules.
174
175## 1.0.0 (November 9, 2017)
176
177This is the same code as 0.7.4, with one incompatible change:
178
179* Require `--allowEmptySource` to sync from empty directory, to help avoid accidental deletion of all files.
180
181## 0.7.4 (November 9, 2017)
182
183New features:
184
185* More efficient uploads by sending SHA1 checksum at the end.
186
187Includes a number of bug fixes:
188
189* File modification times are set correctly when downloading.
190* Fix an off-by-one issue when downloading a range of a file (affects library, but not CLI).
191* Better handling of some errors from the B2 service.
192
193# Developer Info
194
195We 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:
196
197* provide guidance (through the issue reporting system)
198* provide tool assisted code review (through the Pull Request system)
199* maintain a set of integration tests (run with a production cloud)
200* maintain a set of (well over a hundred) unit tests
201* automatically run unit tests on 14 versions of python (including osx, Jython and pypy)
202* format the code automatically using [yapf](https://github.com/google/yapf)
203* use static code analysis to find subtle/potential issues with maintainability
204* maintain other Continous Integration tools (coverage tracker)
205
206You'll need to some Python packages installed. To get all the latest things:
207
208* `pip install --upgrade --upgrade-strategy eager -r requirements.txt -r requirements-test.txt -r requirements-setup.txt`
209
210There is a `Makefile` with a rule to run the unit tests using the currently active Python:
211
212 make setup
213 make test
214
215will install the required packages, then run the unit tests.
216
217To test in multiple python virtual environments, set the enviroment variable `PYTHON_VIRTUAL_ENVS`
218to be a space-separated list of their root directories. When set, the makefile will run the
219unit tests in each of the environments.
220
221Before checking in, use the `pre-commit.sh` script to check code formatting, run
222unit tests, run integration tests etc.
223
224The integration tests need a file in your home directory called `.b2_auth`
225that contains two lines with nothing on them but your account ID and application key:
226
227 accountId
228 applicationKey
229
230We 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*'`.
231
){kind=link}
){kind=link}
){kind=link}
){kind=link}