dropme¶

Command Line Interface tool to manage data in Dropbox workspace (based on official dropbox-sdk-python).

Motivation¶

Get quick access to the user’s Dropbox environment with intuitive commands.

User Documentation¶

How to install¶

From PyPI (stable)

Create isolated Python environment virtualenv venv and activate it:

source venv/bin/activate
Install dropme with pip:

pip install dropme
Configure dropme client according to Configuring section

From GitHub (latest)

Clone dropme repository:

git clone https://github.com/tivaliy/dropme.git.
Configure settings.yaml file (in dropme/settings.yaml) or see configuring section.

token: YOUR_DROPBOX_ACCESS_TOKEN

Create isolated Python environment virtualenv venv and activate it:

source venv/bin/activate
Install dropme with all necessary dependencies:

pip install -r requirements.txt .

Configuring¶

Command Bash Completion¶

To add dropme command bash completion:

dropme complete | sudo tee /etc/bash_completion.d/gc.bash_completion > /dev/null

Restart terminal and activate virtual environment once again.

Dropbox Access Token¶

To use the dropme client, you’ll need to register a new app in the App Console. Select Dropbox API app and choose your app’s permission. You’ll need to use the app key created with this app to access API v2. You have also to generate an access token for your own account through the App Console.

There are several ways to specify Dropbox access token in dropme (the order of search matters):

as an argument of a command:

dropme ls -l --token YOUR_DROPBOX_ACCESS_TOKEN
as a environment variable:

export DBX_AUTH_TOKEN=YOUR_DROPBOX_ACCESS_TOKEN
in ~/.config/dropme/settings.yaml file
in dropme/settings.yaml file

Common Usage¶

To get help on a specific dropme command enter:

$ dropme COMMAND --help

All dropme commands support several global arguments.

CLI tool for managing Dropbox environment.

dropme [--version] [-v | -q] [--log-file LOG_FILE] [--debug] [-t TOKEN]

--version¶: show program’s version number and exit

-v, --verbose¶: Increase verbosity of output. Can be repeated.

-q, --quiet¶: Suppress output except warnings and errors.

--log-file <LOG_FILE>¶: Specify a file to log output. Disabled by default.

--debug¶: Show tracebacks on errors.

-t <TOKEN>, --token <TOKEN>¶: Dropbox access token.

The dropme client can run in two modes:

as a standalone application:

$ dropme
(dropme) whoami
+--------------+------------------------+
| Field        | Value                  |
+--------------+------------------------+
| user         | John Doe               |
| e_mail       | j.doe@example.com      |
| country      | UA                     |
| account_type | basic                  |
+--------------+------------------------+
(dropme) ls -l
+------+---------+---------------------+-----------------------------+
| type | size    | last_modified       | name                        |
+------+---------+---------------------+-----------------------------+
| d    |         |                     | demo/                       |
| d    |         |                     | foo/                        |
| d    |         |                     | dummy/                      |
| -    | 1.11 MB | 2017-10-29 11:12:54 | Start work with Dropbox.pdf |
| -    | 19.0 B  | 2017-11-17 12:41:29 | bar.txt                     |
+------+---------+---------------------+-----------------------------+

as a command with respective sub-command arguments:

$ dropme df
+-----------+-----------------+
| Field     | Value           |
+-----------+-----------------+
| allocated | 2.0 GB          |
| used      | 326.19 MB       |
| available | 1.68 GB (84.1%) |
+-----------+-----------------+

Commands¶

The list of available dropme commands:

cp¶

Copies a file or folder to a different location in the user’s Dropbox.

If the source path is a folder all its content will be copied. If destination path doesn’t exist it will be created.

dropme cp
    [--allow-shared-folder]
    [-r]
    [--allow-ownership-transfer]
    from_path
    to_path

--allow-shared-folder¶: Whether or not allow to copy to a shared folder.

-r, --auto-rename¶: Whether the file should be renamed if there is a name conflict.

--allow-ownership-transfer¶: Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.

from_path¶: Path to a file or folder in the user’s Dropbox to copy.

to_path¶: Destination path in the users’s Dropbox. Will be createdif does not exist.

This command is provided by the dropme plugin.

df¶

Shows information about space usage of the current user’s account.

dropme df
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--prefix PREFIX]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--prefix <PREFIX>¶: add a prefix to all variable names

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

This command is provided by the dropme plugin.

find¶

Searches for files and folders.

Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing.

dropme find
    [-f {csv,json,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--quote {all,minimal,none,nonnumeric}]
    [--sort-column SORT_COLUMN]
    [--start START]
    [--max-results MAX_RESULTS]
    [-m {filename,filename_and_content,deleted_filename}]
    [path]
    query

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

--quote <QUOTE_MODE>¶: when to include quotes, defaults to nonnumeric

--sort-column SORT_COLUMN¶: specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

--start <START>¶: The starting index within the search results (used for paging). Defaults to 0.

--max-results <MAX_RESULTS>¶: The maximum number of search results to return. Defaults to 100.

-m <MODE>, --mode <MODE>¶: The search mode. Note that searching file content is only available for Dropbox Business accounts.

path¶: The path of the directory to make search in, defaults to the root.

query¶: The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. ‘bat c’ matches ‘bat cave’ but not ‘batman car’).

This command is provided by the dropme plugin.

get¶

Downloads a file at a given local path.

dropme get [--revision REVISION] DROPBOX_FILE [LOCAL_FILE]

--revision <REVISION>¶: The revision of a file.

DROPBOX_FILE¶: The path of the file to download.

LOCAL_FILE¶: The path of the file to save data, defaults to current working directory.

This command is provided by the dropme plugin.

ls¶

Lists directory content.

dropme ls
    [-f {csv,json,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--quote {all,minimal,none,nonnumeric}]
    [--sort-column SORT_COLUMN]
    [-l]
    [path]

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

--quote <QUOTE_MODE>¶: when to include quotes, defaults to nonnumeric

--sort-column SORT_COLUMN¶: specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

-l, --long-listing¶: Use a long listing format.

path¶: The path of the directory for printing its content. Defaults to the root.

This command is provided by the dropme plugin.

mkdir¶

Creates a folder at a given path.

dropme mkdir [-r] path

-r, --auto-rename¶: Whether the folder should be renamed if there is a name conflict.

path¶: The path of the folder to create.

This command is provided by the dropme plugin.

mv¶

Moves a file or folder to a different location in the user’s Dropbox.

If the source path is a folder all its content will be moved. If destination path doesn’t exist it will be created.

dropme mv
    [--allow-shared-folder]
    [-r]
    [--allow-ownership-transfer]
    from_path
    to_path

--allow-shared-folder¶: Whether or not allow to move to a shared folder.

-r, --auto-rename¶: Whether the file should be renamed if there is a name conflict.

--allow-ownership-transfer¶: Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.

from_path¶: Path to a file or folder in the user’s Dropbox to move.

to_path¶: Destination path in the users’s Dropbox. Will be createdif does not exist.

This command is provided by the dropme plugin.

put¶

Uploads a file to a specified directory.

If destination directory path doesn’t exist it will be created.

dropme put [-r] [--chunk-size CHUNK_SIZE] file [path]

-r, --auto-rename¶: Whether the file should be renamed if there is a name conflict.

--chunk-size <CHUNK_SIZE>¶: Chunk size of a file content to be uploaded per request in megabytes. Defaults to 10 MB. Note: A single request should not upload more than 150 MB.

file¶: The path to the file to upload.

path¶: The path of the directory to upload file,defaults to the root.

This command is provided by the dropme plugin.

restore¶

Restores file to a specified revision.

dropme restore -r REVISION path

-r <REVISION>, --revision <REVISION>¶: File revision.

path¶: The path to the file to restore.

This command is provided by the dropme plugin.

revs¶

Lists file revisions.

dropme revs
    [-f {csv,json,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--quote {all,minimal,none,nonnumeric}]
    [--sort-column SORT_COLUMN]
    [-m {path,id}]
    [-l LIMIT]
    path

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

--quote <QUOTE_MODE>¶: when to include quotes, defaults to nonnumeric

--sort-column SORT_COLUMN¶: specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

-m <MODE>, --mode <MODE>¶: The revisions for a given file path or id. Defaults to ‘path’. Note, that in the ‘path’ mode, all revisions at the same file path as the latest file entry are returned. If revisions with the same file id are desired, then mode must be set to ‘id’ (useful to retrieve revisions for a given file across moves or renames).

-l <LIMIT>, --limit <LIMIT>¶: The maximum number of revision entries returned. Defaults to 10.

path¶: The path to the file to get the revisions of.

This command is provided by the dropme plugin.

rm¶

Deletes a file or a folder at a given path.

If the path is a folder, all its content will be deleted too.

dropme rm path

path¶: The path of the file or folder to delete.

This command is provided by the dropme plugin.

status¶

Shows status of a specified file or folder.

dropme status
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--prefix PREFIX]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [-i]
    [-d]
    [-m]
    path

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--prefix <PREFIX>¶: add a prefix to all variable names

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

-i, --include-media-info¶: Show media info for file with photo or video content.

-d, --include-deleted¶: Fetch data for deleted file or folder.

-m, --include-has-members¶: Indicate whether or not file has any explicit shared members

path¶: The path to the file to get metadata.

This command is provided by the dropme plugin.

whoami¶

Shows information about the current user’s account.

dropme whoami
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--prefix PREFIX]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [-a]

-f <FORMATTER>, --format <FORMATTER>¶: the output format, defaults to table

-c COLUMN, --column COLUMN¶: specify the column(s) to include, can be repeated

--prefix <PREFIX>¶: add a prefix to all variable names

--noindent¶: whether to disable indenting the JSON

--max-width <integer>¶: Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width¶: Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty¶: Print empty table if there is no data to show.

-a, --all¶: Show information about account in more details.

This command is provided by the dropme plugin.

Release Notes¶

1.1.0¶

Released on Dec 25, 2017.

New dropme revs command
New dropme restore command
Bug fixes

1.0.1¶

Released on Dec 18, 2017.

Links¶

Documentation: http://dropme.readthedocs.io
Source: https://github.com/tivaliy/dropme
Bugs: https://github.com/tivaliy/dropme/issues