acd_cli documentation¶

Installation with PIP¶

If you are new to Python, worried about dependencies or about possibly messing up your system, create and activate virtualenv like so:

cd /parent/path/to/your/new/virtualenv
virtualenv acdcli
source acdcli/bin/activate

You are now safe to install and test acd_cli. When you are finished, the environment can be disabled by simply closing your shell or running deactivate.

Please check which pip command is appropriate for Python 3 packages in your environment. I will be using ‘pip3’ as superuser in the examples.

The recommended and most up-to-date way is to directly install the master branch from GitHub.

pip3 install --upgrade git+https://github.com/yadayada/acd_cli.git

The easiest way is to directly install from PyPI.

pip3 install --upgrade --pre acdcli

ImportError: cannot import name 'IncompleteRead'

apt-get remove python3-pip
easy_install3 pip

Installation on Arch/Debian/RedHat¶

Environment Variables¶

export HTTPS_PROXY="https://user:pass@1.2.3.4:8080/"

Dependencies¶

Uninstalling¶

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 https://www.amazon.com/ap/adam.

Simple (Appspot)¶

You will not have to prepare anything to initiate this authorization method, just run, for example, acd_cli init.

A browser (tab) will open and you will be asked to log into your Amazon account 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 https://tensile-runway-92512.appspot.com/src.

Advanced Users (Security Profile)¶

You must create a security profile and have it whitelisted. Have a look at Amazon’s ACD getting started guide. Select all permissions for your security profile and add a redirect URL to http://localhost.

Put your own security profile data in a file called client_data in the cache directory and have it adhere to the following form.

{
    "CLIENT_ID": "amzn1.application-oa2-client.0123456789abcdef0123456789abcdef",
    "CLIENT_SECRET": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

You may now run acd_cli -v init. The authentication procedure is similar to the one above. A browser (tab) will be opened and you will be asked to log in. Unless you have a local webserver running on port 80, you will be redirected to your browser’s error page. Just copy the URL (e.g. http://localhost/?code=AbCdEfGhIjKlMnOpQrSt&scope=clouddrive%3Aread_all+clouddrive%3Awrite) into the console.

Changing authorization methods¶

If you want to change between authorization methods, go to your cache path (it is stated in the output of acd_cli -v init) and delete the file oauth_data and, if it exists, client_data.

Global Flags/Parameters¶

--verbose (-v) and --debug (-d) will print additional messages to standard error.

--no-log (-nl) will disable the automatic logging feature that saves log files to the cache directory.

--color will set the coloring mode according to the specified argument (auto, never or always). Coloring is turned off by default; it is used for file/folder listings.

--check (-c) sets the start-up database integrity check mode. The default is to perform a full check. Setting the check to quick or none may speed up the initialization for large databases.

--utf (-u) will force the output to be encoded in UTF-8, regardless of the system’s settings.

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:

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

Actions¶

acdcli upload /local/path [/local/next_path [...]] /remote/path

acdcli overwrite /local/path /remote/path

acdcli download /remote/path [/local/path]

some_process | acdcli stream file_name /remote/path

Abort/Resume¶

Incomplete file downloads will be resumed automatically. Aborted file uploads are not resumable at the moment.

Folder or directory hierarchies that were created for a transfer do not need to be recreated when resuming a transfer.

Retry¶

Failed upload, download and overwrite actions allow retries on error by specifying the --max-retries|-r argument, e.g. acd_cli <ACTION> -r MAX_RETRIES.

Exclusion¶

Files may be excluded from upload or download by regex on their name or by file ending. Additionally, paths can be excluded from upload. Regexes and file endings are case-insensitive.

It is possible to specify multiple exclusion arguments of the same kind.

Deduplication¶

Server-side deduplication prevents completely uploaded files from being saved as a node if another file with the same MD5 checksum already exists. acd_cli can prevent uploading duplicates by checking local files’ sizes and MD5s. Empty files are never regarded duplicates.

find¶

The find action will perform a case-insensitive search for files and folders that include the name or name segment given as argument, so e.g. acdcli find foo will find “foo” , “Foobar”, etc.

find-md5¶

find-md5 will search for files that match the MD5 hash given. The location of a local file may be determined like so:

acdcli find-md5 `md5sum local/file | cut -d" " -f1`

find-regex¶

find-regex searches for the specified regex in nodes’ names.

Status¶

The FUSE support is still in its early stage and may be (prone to bugs). acd_cli’s FUSE module has the following filesystem features implemented:

Usage¶

The command to mount the (root of the) cloud drive to the empty directory path/to/mountpoint is

acd_cli mount path/to/mountpoint

A cloud drive folder may be mounted similarly, by

acd_cli mount --modules="subdir=/folder" path/to/mountpoint

Unmounting is usually achieved by the following command

fusermount -u path/to/mountpoint

If the mount is busy, the --lazy (-z) flag can be used. There exists a convenience action acd_cli umount that unmounts all ACDFuse mounts.

export LIBFUSE_PATH="/lib/x86_64-linux-gnu/libfuse.so.2"

acd_cli -d mount -i0 -fg path/to/mountpoint

Using the Issue Tracker¶

The issue tracker is not a forum! This does not mean there is no need for good etiquette, but that you should not post unnecessary information. Each reply will cause a notification to be sent to all of the issue’s participants and some of them might consider it spam.

For minor corrections or additions, try to update your posts rather than writing a new reply. Use strike-through markdown for corrections and put updates at the bottom of your original post.

+1ing an issue or “me, too” replies will not get anything done faster.

Code¶

There are no real programming guidelines as of yet. Please use function annotations for typing like specified in PEP 3107 and, to stay 3.2-compliant, stringified PEP 484 type hints where appropriate. The limit on line length is 100 characters.

It is a generally a good idea to explicitly announce that you are working on an issue.

Please squash your commits and add yourself to the (contributors list <docs/contributors.rst>(_ before making a pull request.

Have a look at (Github’s general guide how to contribute <httpsd//guides.github.com/activities/contributing-to-open-source/#contributing>(_. It’s not necessary to create a feature branch, i.e. you may commit to the master branch.

There is also a (TODO <docs/TODO.rst>(_ list of some of the open tasks.

Donations¶

You might also want to consider (making a donation <httpsd//www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=V4V4HVSAH4VW8>(_ to further the development of acd_cli.

General / API¶

• switch to multiprocessing (?)
• metalink support (?)

API¶

• support of node labels
• support for assets (?)
• favorite support (feature not yet announced officially)
• rip out the Appspot authentication handler

CLI¶

• unify the find action
• check symlink behavior for different Python versions (#95)

FUSE¶

• invalidate chunks of StreamedResponseCache (implement a time-out)
• respect flags when opening files
• implement flush
• use a filesystem test suite

File Transfer¶

• more sophisticated progress handler that supports offsets
• copy local mtime on upload (#58)
• add path exclusion by argument for download
• piped overwrite

User experience¶

• shell completion for remote directories
• even nicer help formatting
• log coloring

Tests¶

• cache methods
• more functional tests
• fuse module

Documentation¶

• write how-to on packaging plugins (sample setup.py)

0.1.3¶

• plugin mechanism added
• OAuth now via Appspot; security profile no longer necessary
• back-off algorithm for API requests implemented

0.1.2¶

new:

• overwriting of files
• recursive upload/download
• hashing of downloaded files
• clear-cache action

fixes:

• remove-child accepted status code
• fix for upload of files with Unicode characters

other:

• changed database schema