Using the Official Dropbox Command Line Interface (CLI)

June 11, 2013
Nathan and Raymond
Tips and Tricks/ Linux

This article assumes you have already installed Dropbox as per the instructions here.

Installation

Download the Dropbox command line interface or get it via the command line: First make a bin directory, or a directory of your choosing. The examples below all assume you made a bin directory:

mkdir -p ~/bin

Download the CLI interface via wget:

wget -O ~/bin/dropbox.py "https://www.dropbox.com/download?dl=packages/dropbox.py"

Set the permissions so you can execute the CLI interface:

chmod +x ~/bin/dropbox.py

Getting Started

Start off by printing the help menu:

~/bin/dropbox.py help

which will show you all the commands you can use

status       get current status of the dropboxd
help         provide help
puburl       get public url of a file in your dropbox
stop         stop dropboxd
running      return whether dropbox is running
start        start dropboxd
filestatus   get current sync status of one or more files
ls           list directory contents with current sync status
autostart    automatically start dropbox at login
exclude      ignores/excludes a directory from syncing

As the help menu shows, to start Dropbox, simply type

~/bin/dropbox.py start

If successful, it should show

Starting Dropbox...Done!

Then check its status with

~/bin/dropbox.py status

Commands

STATUS

Description

get current status of the dropboxd

Usage

Basic usage dropbox.py status Example ~/bin/dropbox.py status Combined with “watch” command watch ‘~/bin/dropbox.py status’

Sample output

$ ~/bin/dropbox.py status
Indexing 317 files...
$ ~/bin/dropbox.py status
Idle

HELP

Description

provide help

Usage

Basic usage dropbox.py help Example ~/bin/dropbox.py help Command help usage dropbox.py help COMMAND Example ~/bin/dropbox.py help exclude

Sample output

$ ~/bin/dropbox.py help
Dropbox command-line interface
commands:

Note: use dropbox help <command> to view usage for a specific command.

status       get current status of the dropboxd
help         provide help
puburl       get public url of a file in your dropbox
stop         stop dropboxd
running      return whether dropbox is running
start        start dropboxd
filestatus   get current sync status of one or more files
ls           list directory contents with current sync status
autostart    automatically start dropbox at login
exclude      ignores/excludes a directory from syncing
$ ~/bin/dropbox.py help puburl
dropbox puburl FILE
Prints out a public url for FILE.

PUBURL

Description

get public url of a file in your dropbox

Usage

Basic usage dropbox.py puburl FILE Example ~/bin/dropbox.py puburl ~/Dropbox/Public/file.zip

Sample output

$ ~/bin/dropbox.py puburl ~/Dropbox/Public/file.zip
http://dl.dropbox.com/u/XXXXXXX/file.zip

If not used on a file in your Public folder, you will get an error message:

$ ~/bin/dropbox.py puburl ~/Dropbox/myFolder/file.zip 
Couldn't get public url: Unknown Error

STOP

Description

stop dropboxd

Usage

Basic usage dropbox.py stop Example ~/bin/dropbox.py stop

Sample output

$ ~/bin/dropbox.py stop
Dropbox daemon stopped.

RUNNING

Description

return whether dropbox is running

Used in scripts to check if Dropbox is running. This command does not output anything to the user.

Extra Info

$ ~/bin/dropbox.py help running
dropbox running
Returns 1 if running 0 if not running.

Usage

Basic usage dropbox.py running Example ~/bin/dropbox.py running

Sample output

$ ~/bin/dropbox.py running
<no output>

EXCLUDE

Description

ignores/excludes a directory from syncing

Used in scripts to check if Dropbox is running. This command does not output anything to the user.

Extra Info

$ ~/bin/dropbox.py help exclude
dropbox exclude [list]
dropbox exclude add [DIRECTORY] [DIRECTORY] ...
dropbox exclude remove [DIRECTORY] [DIRECTORY] ...
"list" prints a list of directories currently excluded from syncing.  
"add" adds one or more directories to the exclusion list, then resynchronizes Dropbox. 
"remove" removes one or more directories from the exclusion list, then resynchronizes Dropbox.
With no arguments, executes "list". 
Any specified path must be within Dropbox.

Usage

List usage: dropbox.py exclude list Example ~/bin/dropbox.py exclude Example ~/bin/dropbox.py exclude list Add exclusion usage dropbox.py exclude add DIRECTORY Example ~/bin/dropbox.py exclude add ~/Dropbox/MyExcludedFolder Remove exclusion usage dropbox.py exclude remove DIRECTORY Example ~/bin/dropbox.py exclude remove ~/Dropbox/MyReincludedFolder

Sample output

$ ~/bin/dropbox.py exclude list
Excluded: 
Dropbox/backup
Dropbox/documents
Dropbox/music
Dropbox/papers
Dropbox/photos
Dropbox/pictures
$ ~/bin/dropbox.py exclude add ~/Dropbox/MyExclude1 ~/Dropbox/MyExclude2 ~/Dropbox/MyExclude3
[...]

Helpful

(17) Unhelpful

(5)

Pingback: Project: Aquarium Server - mrpc’s Blog()
Pingback: Cloud Storage Services on Linux Platforms | LinuxNov()
Francois

Is there a way to pause/unpause the synchronization from the command line?
- un person
  
  Is there a way to start Dropbox in pause-sync mode, from the command line?
- Nguyen Vu Ngoc Tung
  
  Hi François,
  Unfortunately, I forgot to synchronize dropbox before leaving the office. When I come to my house, I’ve done the thing as you want to know. There is a simple way (I guess you want to remote you Linux server) using ssh/terminal:
  – Stop dropbox by the command: dropbox stop
  – Then start dropbox: dropbox start. Your files will be synchronized automatically.
Hardus

I just want to add that I had trouble running the dropbox.py, I had it executable and all the tutorials show for example: dropbox.py help, that don’t work like that, you have to run it as a executable like: ./dropbox.py help then only it works.
- Tim Harman
  
  That’s because the place you’re trying to execute it isn’t in your path.
Michael

I got the following error during synchronization of files that cannot be accessed because the message Dropbox throws contains characters that cannot be read by the script.

UnicodeEncodeError: ‘latin-1′ codec can’t encode character u’u201e’ in position 10: ordinal not in range(256)

Anybody knows what I can do to solve this?

I’m using Debian 7.0 (Wheezy) 64bit with an installed Dropbox client fetched by the linked script from this guide.

Since the mentioned character is the DOUBLE LOW-9 QUOTATION MARK („) it appears that it comes from one of the German messages Dropbox sends to the client. Maybe it is just a configuration of the client itself, I don’t know this.

I’d change the language of the client to English if someone tells me how. But fixing the error would be nice.
- Andreas
  
  When starting the dropboxd, make sure none of the ENV vars are set to de_DE…don’t know which ones exactly make the difference.
Stanislav

Very useful cli program. In my opinion it lacks such a feature as a callback. For example, when after Dropbox starts and finishes the synchronization
Pingback: Guidelines to setup a perfect Digital Ocean VPS | NARGA()
Harringer

Is there any relationship between the dropboxd (dropox daemon) and the usual dropbox client? I thought I could use the dropbox CLI to track the activity of the dropbox client, but it seems that both apps are independent.
Pingback: How To Install & Configure Headless Dropbox as a Service on Ubuntu 12.04 | vDevices()
tcumming

If someone shares their dropbox with me by sending me a url, how can I reference it with a cli? What if it’s a shared directory? What if I want to modify a file in a directory they’ve shared with me?
Achim

I am glad I discovered this command line utility — very helpful. However, I was hoping for a command that would list the recent synchronisation events (much like the “events” page that I get when I log into the online Dropbox account).
Chad

Dropbox… almost all your stuff works great, with the exception of this daemon and command line utility….

How about something to pause the syncing, and something to exclude all the folders in my dropbox while letting me pick only what I do want to download…
- Qing
  
  Yeah, that’s exactly what i need also, it’s really annoying to add new folders into the excluding list when I created new folders in other machine…
  - Fab Milky
    
    +1
  - Simen Schikulski
    
    +1
  - John Randall
    
    +1
  - Tim Malone
    
    +1
    - Braden Napier
      
      +1
      - Bobjohnson
        
        +1
- pE
  
  I know this was posted a year ago, but people have been agreeing to it more recently. To exclude all files/folders, go to your dropbox folder then type “~/bin/dropbox.py exclude add *”. This will exclude everything in your dropbox folder from syncing. Then, if you want to start syncing the folder “dir”, type “~/bin/dropbox.py exclude remove dir”
  - tylercollier
    
    Thanks pE. To clarify, make sure you run the command from your dropbox folder, even if the python script is elsewhere. E.g. if the python script is in your `~/downloads` folder, it might look like this:
    
    user@server: ~/Dropbox $ ~/downloads/dropbox.py exclude add *
    
    It will sit and think for a while, and if it excludes something, you’ll see it say “Excluded:” and then a list.
  - Tim Malone
    
    Just to clarify, are you saying this works…. or is it a feature request? I haven’t been able to get wildcards to work like this and I would dearly love to!
RobbieD

How do you exclude folders that include spaces? I have tried:

~/.dropbox/dropbox.py exclude add “~/Dropbox/Camera Uploads”

… but that doesn’t work.
- RobbieD
  
  Sorry – my bad… This worked:
  
  ~/.dropbox/dropbox.py exclude add ~/Dropbox/Camera Uploads
- Duke Igthorn
  
  What also works well is:
  ~/.dropbox/dropbox.py exclude add ~/Dropbox/’Camera Uploads’
  with single quotations. 🙂
- Tim Malone
  
  I’m having issues using both of the above commands (with the before space, and with the single quotes around the portion of the directory with spaces). Takes ages.. and then eventually finishes with no response, and no change to the excluded files. Would love to know if anyone has worked out the proper syntax for this – it is very hard to test because each command takes hours to complete!
Pingback: Webserver Dropbox Sync | Kingston IT()
Luis Navarro

How can I link with an accoun by this way?. Thanks
- franc
  
  In the very beginning of this article there is a note:
  This article assumes you have already installed Dropbox as per the instructions here:
  http://34.232.119.176/tips-and-tricks/install-dropbox-in-an-entirely-text-based-linux-environment
  I had read over it as well 🙂
Pingback: Synchronizing Dropbox files with Hubic()
Stefan

Is it possible to change the location of the Dropbox directory?
My /home dir is very small and it is not supposed to contain huge data like this.
Pingback: Axross.org – さくらVPSを契約してCentOS6.4をNode.js Webアプリケーションサーバーとして構築するチュートリアル()
Ethan Setnik

It would be great if you could exclude by wildcard.
- Ladislas de Toldi
  
  You actually can.
Hpsaturn

Please implements dropbox shortener url for puburl, thanks!
Mau Lazyhola

This script is very neat. It would be totally awesome if I could exclude with wildcards.

In my particular case I sync database backups for each of my client’s. It would be lot easier to say something like “stop sync everything except ” instead of the current way it works.

Anyway the tool is very powerful. I will upgrade my account pretty soon. Thanks.
OSSAlanR

I get “Couldn’t get public url: Unknown Error” when I give it the name of a folder under a public folder. However, I *can* successfully produce a public URL for this same directory using the web.

How do I get this same behavior from the dropbox.py command line tool?
- Weedy
  
  I just started having the same problem. I setup my alias years ago.
Chris Howard

Is the exclude list saved in a config file somewhere that I can just edit directly?
George Papadopoulos

How can I download the CLI via the command line using curl instead of wget (I’m really new to command line operation so I’m clueless)?
Mark Grundy

The one thing I would really like from command line is to be able to find out the space used/free in the dropbox.
DaylateDollarshort

mkdir -p ~/bin
curl -O https://linux.dropbox.com/packages/dropbox.py
chmod +x ~/bin/dropbox.py
Select Field

hey this is great you should put a link to this wiki on the install page: https://www.dropbox.com/install?os=lnx for linux
Chris

It would be great to get a way to change the folder… right now it’s kinda shitty.
Pingback: Ubuntu as a home server. Part 5. Reliability.()
Igor Soarez

Please provide a way to change synced folder path
saeioul

For Gilgamesh sake, include a proxy settings option
Mrtgang

how to upload a file/directory ?
brycenesbittt

Ok, but how do I link to a dropbox from the command line?
nobrevet

let me get this straight…. if I remove from the exclusion list, it will download the folder from dropbox, wont it?
olgabot

When I have many (100,000+) files syncing or indexing, the command line client will die without notice. I can’t decrypt these binary files in ~/.dropbox/logs/(d+) but would like a notice. I suspect it’s running out of memory and not telling me 🙁
David Susen

I have had Dropbox running on my Ubuntu Linux box for months. Just installed dropbox.py and typed “./dropbox.py status” – it replied Dropbox isn’t running … typed “./dropbox.ph start” it replied Starting Dropbox (when it was already) and then The Dropbox daemon is not installed! Run “dropbox start -i” to install the daemon. Somehow it does not know that it is running. How do I smarten it up?
Juan Rodriguez-Flores

How do you connect an existing dropbox account?
Pingback: Guidelines to setup a perfect Digital Ocean VPS - TecHub()
BustedChain

I wish this had “include” support…meaning that everything would be excluded except for specifically included directories.
Pingback: Apple:How to launch Google Drive in another user's session? – Apple Questions()
sussycadillac

This thing is completely unreliable:

$ ~/bin/dropbox.py status
Dropbox isn’t running!
$ ps -aux | grep dropbox
gato 8703 0.1 0.7 147112 30648 pts/1 Sl 11:28 0:00 /home/gato/.dropbox-dist/dropbox-lnx.x86-3.10.8/dropbox
$ ~/bin/dropbox.py start
Dropbox isn’t running!
Dropbox is already running!
$ ~/bin/dropbox.py status
Dropbox isn’t running!
Pingback: Dagens serverarbete | Cloudheaven()
Braden Napier

+100 for the ability to auto exclude all current and future directories unless marked!
Braden Napier

Is there no way to change accounts? I have a dropbox with like 200gb on it and i have a server i want to use this with that only has a partition for 5gb… so im screwed? if i start this it shuts down my server cause it runs out of disk space so my only way of fixing this was to create a unique dropbox account and sync the only folder i want to that… but now i cant tell the CLI to use that new account instead… wow.
NewModelNo15

Very helpful, worked exactly as described!
Rogier Lommers

The python.py script requires Python 2 at the moment. Any idea when it will be ported to Python 3?
bobbyriled

Is there a command for viewing file activity?

Installation

Getting Started

Commands

STATUS

Description

Usage

Sample output

HELP

Description

Usage

Sample output

PUBURL

Description

Usage

Sample output

STOP

Description

Usage

Sample output

RUNNING

Description

Extra Info

Usage

Sample output

EXCLUDE

Description

Extra Info

Usage

Sample output

Related Articles

Sync any number of folders with Dropbox – and protect their content with Cloudifile

Gmail with attach-dropbox files

Extensions to make Dropbox more awesome

Send any books to your Kindle from Dropbox automatically

Encrypt stuff on Dropbox

Sync computer games through Dropbox