Skip to main content

a command line interface for Amazon Cloud Drive

Project description

Donate via PayPal Join the chat at


acd_cli provides a command line interface to Amazon Cloud Drive and allows mounting your cloud drive using FUSE for read access. It is currently in beta stage.


  • local node caching

  • addressing of remote nodes via a pathname (e.g. /Photos/kitten.jpg)

  • simultaneous uploads/downloads, retry on error

  • basic plugin support

File operations

  • tree or flat listing of files and folders

  • upload/download of single files and directories

  • folder creation

  • trashing/restoring

  • moving/renaming nodes

Quick start


The easiest way is to directly install from github. Please check which pip command is appropriate for Python 3 packages in your environment. I will be using ‘pip3’ in the examples.

pip3 install --upgrade git+

To install from a downloaded or cloned directory, run pip in the project’s root directory like so:

pip3 install --upgrade .

If you do not want to install, have a look at the necessary dependencies.

First Run

On the first start of the program (try acd_cli sync), you will have to complete the OAuth procedure. A browser tab will open and you will be asked to log in or grant access for ‘acd_cli_oa’. Signing in or clicking on ‘Continue’ will download a JSON file named oauth_data, which must be placed in the cache directory displayed on screen (e.g. /home/<USER>/.cache/acd_cli).

You may view the source code of the Appspot app that is used to handle the server part of the OAuth procedure at

Advanced Users

Alternatively, you may put your own security profile data in a file called client_data in the cache directory. It needs to be created prior to starting the program and adhere to the following form.

    "CLIENT_ID": "",

Your security profile must be able to redirect to http://localhost. The procedure is similar to the above, the difference is that you will be asked to paste the redirect URL into your shell.


Most actions need the node cache to be initialized and up-to-date, so please run a sync. A sync will fetch the changes since the last sync or the full node list if the cache is empty.

The following actions are built in

sync (s)            refresh node list cache; necessary for many actions
clear-cache (cc)    clear node cache [offline operation]

tree (t)            print directory tree [offline operation]
children (ls)       list a folder's children [offline operation]
find (f)            find nodes by name [offline operation]
find-md5 (fm)       find files by MD5 hash [offline operation]

upload (ul)         file and directory upload to a remote destination
overwrite (ov)      overwrite file A [remote] with content of file B [local]
download (dl)       download a remote folder or file; will skip existing local files

create (c, mkdir)   create folder using an absolute path

list-trash (lt)     list trashed nodes [offline operation]
trash (rm)          move node to trash
restore (re)        restore node from trash

move (mv)           move node A into folder B
rename (rn)         rename a node

resolve (rs)        resolve a path to a node ID

usage (u)           show drive usage data
quota (q)           show drive quota [raw JSON]
metadata (m)        print a node's metadata [raw JSON]

mount               mount the cloud drive at a local directory

Please run acd_cli --help to get a current list of the available actions. You may also get a list of further arguments and their order of an action by calling acd_cli [action] --help.

You may provide most node arguments as a 22 character ID or a UNIX-style path. Trashed nodes’ paths might not be able to be resolved correctly; use their ID instead.

The number of concurrent transfers can be specified using the argument -x [no].

When uploading/downloading large amounts of files, it is advisable to save the log messages to a file. This can be done by using the verbose argument and appending 2> >(tee acd.log >&2) to the command.

Files can be excluded via optional parameter by file ending, e.g. -xe bak, or regular expression on the whole file name, e.g. -xr "^thumbs\.db$". Both exclusion methods are case insensitive.

Exit status

When the script is done running, its exit status can be checked for flags. If no error occurs, the exit status will be 0. Possible flag values are:



argument error


failed file transfer


upload timeout


hash mismatch


error creating folder


file size mismatch


cache outdated




If multiple errors occur, their values will be compounded by a binary OR operation.


First, create an empty mount directory, then run acd_cli mount path/to/mountpoint. To unmount later, run fusermount -u path/to/mountpoint.



Basic operations

List directory







OS-level trashing

partially [2]

View trash


Automatic sync

Hard links

partially [3]

Symbolic links

Usage example

In this example, a two-level folder hierarchy is created in an empty cloud drive. Then, a relative local path local/spam is uploaded recursively using two connections.

$ acd_cli sync

$ acd_cli ls /
  [PHwiEv53QOKoGFGqYNl8pw] [A] /

$ acd_cli mkdir /egg/
$ acd_cli mkdir /egg/bacon/

$ acd_cli upload -x 2 local/spam/ /egg/bacon/
  [################################]   100.0% of  100MiB  12/12  654.4KB/s

$ acd_cli tree

The standard node listing format includes the node ID, the first letter of its status and its full path. Possible statuses are “AVAILABLE” and “TRASH”.


Please run acd_cli delete-everything first to delete your authentication and node data in the cache path. Then, use pip to uninstall:

pip3 uninstall acdcli

Then, revoke the permission for acd_cli_oa to access your cloud drive in your Amazon profile, more precisely at

Known Issues

API Restrictions

  • uploads of large files >10 GiB may be successful, yet a timeout error is displayed (please check manually)

  • the maximum (upload) file size seems to be in the range of 40 and 100 GiB

  • storage of node names is case-preserving, but not case-sensitive (this concerns Linux users mainly)

  • it is not possible to share or delete files


Feel free to use the bug tracker to add issues. You might find the --verbose and, to a lesser extent, --debug options helpful.

If you want to contribute code, have a look at Github’s general guide how to do that. There is also a TODO list.

You might also want to consider making a donation to further the development of acd_cli.


Python packages

  • appdirs

  • dateutils (recommended)

  • requests >= 2.1.0

  • requests-toolbelt (recommended)

  • sqlalchemy

Recommended packages are not strictly necessary; but they will be preferred to workarounds (in the case of dateutils) and bundled modules (requests-toolbelt).

If you want to the dependencies using your distribution’s packaging system and are using a distro based on Debian ‘jessie’, the necessary packages are python3-appdirs python3-dateutil python3-requests python3-sqlalchemy.


For the mounting feature, fuse >= 2.6 is needed according to pyfuse. On a Debian-based distribution, the according package should simply be named ‘fuse’.

Recent Changes


  • FUSE read support added


  • sync speed-up

  • node listing format changed

  • optional node listing coloring added (for Linux or via LS_COLORS)

  • re-added possibility for local OAuth


  • curl dependency removed

  • added job queue, simultaneous transfers

  • retry on error


  • setuptools support

  • workaround for download of files larger than 10 GiB

  • automatic resuming of downloads

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

acdcli-0.1.tar.gz (47.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page