Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
a Python API/client that manipulates files on (a.k.a
branch: master

This branch is 34 commits behind hzheng:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



pybox is a Python API/client that manipulates files on (a.k.a It can display user's account information, file structure, and file information, manage(move/rename/delete/upload/download) files and directories, and most importantly, it can compare and synchronize directories between client and server.


Please take the following steps:

  1. Obtain an API key from here.

  2. Copy boxrc.example to user's home directory, rename it to .boxrc in a POSIX system (e.g. Unix, Linux, Mac OS X) or _boxrc in a non-POSIX system(e.g. Windows).

  3. Edit .boxrc/_boxrc: replace api_key's value(YOUR_API_KEY) with the API key you've got in step 1.

  4. Copy box-logging.conf.example to box-logging.conf.

  5. Edit(optionally) box-logging.conf, e.g. change 'BOX.LOG' to different name or path. If you'd like to put this log configuration file to a different directory, don't forget to add an environment variable named LOG_CONF_DIR.

  6. Open a command terminal, change directory to the pybox directory, then run:

    python pybox/ -U YOUR_LOGIN_EMAIL -p -a

    Replace the above email with your actual login email on, and type your password when prompted. If login/password combination is correct, you will get your auth token from the output(something like "auth_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

  7. Edit .boxrc/_boxrc again. Replace(or add) account section(YOUR_ACCOUNT_LOGIN) with your login(actually, it can be any string, not necessarily the same as your box login email), replace auth_token value(YOUR_AUTH_TOKEN) with the one you've got in step 6.

  8. If you have multiple box accounts, just repeat step 6 and 7.

If everything goes smoothly, you are now free to manipulate your files on the box account(s) without typing password any more. Generally the command is:

python pybox/ -U YOUR_LOGIN [options] [args]

Please be noticed that this time YOUR_LOGIN is the string you set in step 7.

All supported options are listed as follows:

  • -U, --username specify username/email

  • -p, --password prompt password (only needed when auth_token is not found)

  • -a, --auth-token print auth token

  • -I, --account-info get box account information

  • -t, --target specify target type(f for file<default>, d for directory)

  • -l, --list list directory

  • -w, --what-id get a path(server-side)'s id

  • -i, --info get file information

  • -M, --mkdir make a directory

  • -R, --remove remove a file or directory

  • -m, --move move a file or directory

  • -r, --rename rename a file or directory

  • -1, --onelevel list one level files

  • -z, --zip list file tree in zip format

  • -N, --nofiles only list directory

  • -s, --simple show simple information

  • -c, --chdir change directory

  • -d, --download download file

  • -u, --upload upload file

  • -P, --plain-name use plain name(server-side) instead of id

  • -C, --compare compare local and remote directories

  • -S, --sync sync local and remote directories

  • -n, --dry-run show what would have been transferred when sync

  • -f, --from-file read arguments from file(arguments separated by line break)


Assume all the following operations are performed on Bob's account.

  • show account information:

    python pybox/ -Ubob -I
  • list all files(caution: this could be VERY VERY slow):

    python pybox/ -Ubob -l 0 (0 is the root id)
  • list all first-level files with fewer details:

    python pybox/ -Ubob -ls1 0
  • create a directory dir1 under root:

    python pybox/ -Ubob -M dir1
  • create a directory dir2 under dir1:

    python pybox/ -Ubob -P -c dir1 -M dir2
  • get directory dir1/dir2(starting from root)'s id:

    python pybox/ -Ubob -w dir1/dir2
  • upload file file1, file2 and directory dir3 to root directory:

    python pybox/ -Ubob -u file1 file2 dir3
  • upload file3 to a directory whose id is 1005691453

    python pybox/ -Ubob -c1005691453 -u file3
  • upload file4 to a directory whose path is 'path1/path2'(starting from root)

    python pybox/ -Ubob -P -c path1/path2 -u file4
  • remove a file whose id is 1005181453

    python pybox/ -Ubob -R 1005181453
  • remove a directory whose path is path1/path2(starting from root)

    python pybox/ -Ubob -PR -td path1/path2
  • rename file file1 to, file file2 to

    python pybox/ -Ubob -Pr file1 file2
  • rename directory dir1 to dir2

    python pybox/ -Ubob -Pr -td dir1 dir2
  • move a file with id 1025611460 to a directory with id 225236230

    python pybox/ -Ubob -m 1025611460 225236230
  • move directory dir1 to directory dir2, directory dir3/dir4 to directory dir5/dir6/dir7

      python pybox/ -Ubob -td -Pm dir1 dir2 dir3/dir4 dir5/dir6/dir7
  • download a directory dir1/dir2

    python pybox/ -Ubob -td -Pd dir1/dir2
  • compare a local directory /Users/bob/dir1 with a remote directory dir2/dir3

    python pybox/ -Ubob -td -PC /Users/bob/dir1 dir2/dir3
  • sync a local directory /Users/bob/dir1(source) with a remote directory dir2/dir3(destination)

      python pybox/ -Ubob -PS /Users/bob/dir1 dir2/dir3


Box API documentation


Copyright 2011-2012 Hui Zheng

Released under the MIT License.

Something went wrong with that request. Please try again.