SYNC AGENT AND CLI OVERVIEW

The odrive Sync Agent provides advanced users with a flexible, scriptable interface to odrive’s Progressive Sync engine. Use it to bring cloud access and sync to almost any environment.

The odrive Sync Agent can be used on Windows (7+), MacOS (10.7+), Linux (glibc 2.11+), ARMv6 i.e. Raspberry Pi (glibc 2.13+) operating systems.

Sync Agent Service (odriveagent / odriveagent.exe)

This is the sync engine and runs persistently. It will react to filesystem and remote changes and listen for commands from the odrive CLI.

odrive CLI (odrive / odrive.exe / odrive.py)

This is the client interface to the Sync Agent server. The odrive CLI is used from the command-line or from shell scripts to control and enhance Sync Agent behavior. The client is written in python and can be extended and customized to add additional functionality and automation, as well.

Support for:

Dropbox, Google Drive, Amazon Drive/Photos, Microsoft OneDrive, Slack, SharePoint, Office 365, Facebook, Microsoft OneDrive for Business, Box, Amazon S3, Wasabi, DigitalOcean Spaces, DreamHost DreamObjects, MinIO, S3 Compatible Storage, Google Cloud Storage, Backblaze B2, FTP, FTPS, SFTP, WebDAV, 4shared, ADrive, HiDrive, and Yandex Disk

INSTALL ON LINUX

The following install commands are convenient one-liners, but are not required to install odrive. You can simply download the two binary archives (agent and CLI), extract them, and run.

Direct Download links

odrive Sync Agent/CLI headless install via command line:

Run the following command in your terminal to download and install the odrive Sync Agent to ~/.odrive-agent. This will download the odrive Agent service, the odrive Agent python client, and the odrive Agent binary client.

Download/Install for 64-bit Linux Download/Install for 32-bit Linux Download/Install for ARM-based Linux/RPi od="$HOME/.odrive-agent/bin" && curl -L "https://dl.odrive.com/odrive-py" --create-dirs -o "$od/odrive.py" && curl -L "https://dl.odrive.com/odriveagent-lnx-64" | tar -xvzf- -C "$od/" && curl -L "https://dl.odrive.com/odrivecli-lnx-64" | tar -xvzf- -C "$od/" od="$HOME/.odrive-agent/bin" && curl -L "https://dl.odrive.com/odrive-py" --create-dirs -o "$od/odrive.py" && curl -L "https://dl.odrive.com/odriveagent-lnx-32" | tar -xvzf- -C "$od/" && curl -L "https://dl.odrive.com/odrivecli-lnx-32" | tar -xvzf- -C "$od/" od="$HOME/.odrive-agent/bin" && curl -L "https://dl.odrive.com/odrive-py" --create-dirs -o "$od/odrive.py" && curl -L "https://dl.odrive.com/odriveagent-rpi" | tar -xvzf- -C "$od/" && curl -L "https://dl.odrive.com/odrivecli-rpi" | tar -xvzf- -C "$od/"

RUN ON LINUX

In the following examples, the agent and CLI binaries we put into $HOME/.odrive-agent/bin/

(Optional) To run the odrive Sync Agent server in the background, you can use a command like the following command in your terminal

Run in the background nohup "$HOME/.odrive-agent/bin/odriveagent" > /dev/null 2>&1 &

You can also just run the command normally.

ex: $HOME/.odrive-agent/bin/odriveagent

Now the odrive Sync Agent server is running and you can use the odrive CLI to control it. For example, the following terminal command will display the available client commands:

Binary Client (help) Python Client (help) "$HOME/.odrive-agent/bin/odrive" -h python "$HOME/.odrive-agent/bin/odrive.py" -h

The following terminal command will show the current status of the odrive Sync Agent:

Binary Client (status) Python Client (status) "$HOME/.odrive-agent/bin/odrive" status python "$HOME/.odrive-agent/bin/odrive.py" status

For detailed information and examples on using Agent, refer to the Using the odrive Sync Agent

INSTALL ON WINDOWS

The following install command is a convenient one-liner, but is not required to install odrive. You can simply download the two binary archives (agent and CLI), extract them, and run.

Direct Download links

odrive Sync Agent/CLI headless install via command line:

Open up powershell and run the following command to download and install the odrive Sync Agent to .odrive-agent in your user home directory. This will download the odrive Agent service, the odrive Agent python client, and the odrive Agent binary client. The command doesn't give much feedback, so just give it some time

Download/Install via Windows Powershell $o="$HOME\.odrive-agent\bin";mkdir "$o" -FORCE;(New-Object System.Net.WebClient).DownloadFile("https://dl.odrive.com/odrive-py","$o\odrive.py");(New-Object System.Net.WebClient).DownloadFile("https://dl.odrive.com/odriveagent-win", "$o\o.zip");$shl=new-object -com shell.application; $shl.namespace("$o").copyhere($shl.namespace("$o\o.zip").items(),0x10);del "$o\o.zip";(New-Object System.Net.WebClient).DownloadFile("https://dl.odrive.com/odrivecli-win", "$o\oc.zip");$shl=new-object -com shell.application; $shl.namespace("$o").copyhere($shl.namespace("$o\oc.zip").items(),0x10);del "$o\oc.zip";

RUN ON WINDOWS

In the following examples, the agent and CLI binaries we put into $HOME/.odrive-agent/bin/

(Optional) To run the odrive Sync Agent server in the background, you can use the following command in powershell:

Run in the background via Windows Powershell Start-Job { & "$HOME\.odrive-agent\bin\odriveagent.exe" }

You can also just run the command normally.

ex: $HOME/.odrive-agent/bin/odriveagent

Now the odrive Sync Agent server is running and you can use the odrive CLI to control it. For example, the following powershell command will display the available client commands:

Binary Client (help) Python Client (help) & "$HOME\.odrive-agent\bin\odrive.exe" -h python "$HOME\.odrive-agent\bin\odrive.py" -h

The following powershell command will show the current status of the odrive Sync Agent:

Binary Client (status) Python Client (status) & "$HOME\.odrive-agent\bin\odrive.exe" status python "$HOME\.odrive-agent\bin\odrive.py" status

For detailed information and examples on using Agent, refer to the Using the odrive Sync Agent

INSTALL ON MACOS

The following install command is a convenient one-liner, but is not required to install odrive. You can simply download the two binary archives (agent and CLI), extract them, and run.

Direct Download links

odrive Sync Agent/CLI headless install via command line:

Run the following command in your terminal to download and install the odrive Sync Agent to ~/.odrive-agent. This will download the odrive Agent service, the odrive Agent python client, and the odrive Agent binary client.

Download/Install via terminal od="$HOME/.odrive-agent/bin" && curl -L "https://dl.odrive.com/odrive-py" --create-dirs -o "$od/odrive.py" && curl -L "https://dl.odrive.com/odriveagent-osx" | tar -xvzf- -C "$od/" && curl -L "https://dl.odrive.com/odrivecli-osx" | tar -xvzf- -C "$od/"

RUN ON MACOS

In the following examples, the agent and CLI binaries we put into $HOME/.odrive-agent/bin/

(Optional) To run the odrive Sync Agent server in the background, you can use the following command in your terminal:

Run in the background via terminal nohup "$HOME/.odrive-agent/bin/odriveagent.app/Contents/MacOS/odriveagent" > /dev/null 2>&1 &

You can also just run the command normally.

ex: $HOME/.odrive-agent/bin/odriveagent

Now the odrive Sync Agent server is running and you can use the odrive CLI to control it. For example, the following terminal command will display the available client commands:

Binary Client (help) Python Client (help) "$HOME/.odrive-agent/bin/odrive" -h python "$HOME/.odrive-agent/bin/odrive.py" -h

The following terminal command will show the current status of the odrive Sync Agent:

Binary Client (status) Python Client (status) "$HOME/.odrive-agent/bin/odrive" status python "$HOME/.odrive-agent/bin/odrive.py" status

For detailed information and examples on using Agent, refer to the Using the odrive Sync Agent

USING THE CLI/AGENT (ALL PLATFORMS)

In the following examples, the agent and CLI binaries we put into $HOME/.odrive-agent/bin/

1. Create an odrive account

Click here to create an odrive account

OR

Click here to login to your existing odrive account

2. Create an auth key for odrive Agent

Click Here to go to your Authentication Codes screen and click on “Create Auth Key” to create an auth key.

You can also get to this screen by navigating to your Profile and then clicking on Auth Keys

3. Authenticate odrive Agent

Use your new key to authenticate your odrive Sync Agent.

odrive authenticate [auth key]

MacOS/Linux Binary Client (authenticate) Windows Binary Client (authenticate) Python Client (authenticate) "$HOME/.odrive-agent/bin/odrive" authenticate 00000000-0000-0000-0000-000000000000-00000000 & "$HOME\.odrive-agent\bin\odrive.exe" authenticate 00000000-0000-0000-0000-000000000000-00000000 python "$HOME/.odrive-agent/bin/odrive.py" authenticate 00000000-0000-0000-0000-000000000000-00000000

4. Create an agent mount

This will mount the root of your odrive to the local folder “odrive-agent-mount”.

First, make sure the local folder exists before attempting to mount. In our example we are going to create a new folder named "odrive-agent-mount" in the user's home folder. You can also use an existing local folder. See below for more details.

MacOS/Linux/Windows Powershell mkdir "$HOME/odrive-agent-mount"

You can then mount using the following command:

odrive mount [local path] [remote odrive path]

It is possible to mount an existing folder with data in it to a folder in your odrive. For example:

odrive mount $HOME/Documents /odrive/Google Drive/Documents

This will merge the content of the local folder with the remote folder (you can do this with empty folders on either side, as well).

Important Note: You do not want to mount the root of the odrive folder to an existing local folder with data in it.

OS X/Linux Binary Client (mount) Windows Binary Client (mount) Python Client (mount) "$HOME/.odrive-agent/bin/odrive" mount "$HOME/odrive-agent-mount" / & "$HOME\.odrive-agent\bin\odrive.exe" mount "$HOME\odrive-agent-mount" / python "$HOME/.odrive-agent/bin/odrive.py" mount "$HOME/odrive-agent-mount" /

In this example, '$HOME/.odrive-agent-mount' will now contain all of your linked storage.

5. Sync an odrive folder

odrive sync [local path to .cloudf placeholder file]_ [--recursive] [--nodownload]

Optional parameters:

--recursive - Will recursively sync the contents of the folder

--nodownload - When used with --recursive, all folders will be expanded, but no files downloaded (all files remain placeholders)

OS X/Linux Binary Client (sync) Windows Binary Client (sync) Python Client (sync) "$HOME/.odrive-agent/bin/odrive" sync "$HOME/odrive-agent-mount/Dropbox.cloudf" --recursive --nodownload & "$HOME\.odrive-agent\bin\odrive.exe" sync "$HOME\odrive-agent-mount\Dropbox.cloudf" --recursive --nodownload python "$HOME/.odrive-agent/bin/odrive.py" sync "$HOME/odrive-agent-mount/Dropbox.cloudf" ---recursive --nodownload

6. Sync a file

odrive sync [local path to .cloud placeholder file]

OS X/Linux Binary Client (sync) Windows Binary Client (sync) Python Client (sync) "$HOME/.odrive-agent/bin/odrive" sync "$HOME/odrive-agent-mount/Dropbox/myfile.txt.cloud" & "$HOME\.odrive-agent\bin\odrive.exe" sync "$HOME\odrive-agent-mount\Dropbox\myfile.txt.cloud" python "$HOME/.odrive-agent/bin/odrive.py" sync "$HOME/odrive-agent-mount/Dropbox/myfile.txt.cloud"

CLI COMMANDS

📘 Use -h with any command to provide information about that command authenticate

Authenticate odrive with an auth key usage: odrive authenticate [-h] authKey positional arguments:

authKey - auth key from https://www.odrive.com/account/authcodes example: odrive authenticate 00000000-0000-0000-0000-000000000000-00000000 mount

Mount remote odrive path to the specified local folder usage: usage: odrive mount [-h] localPath remotePath positional arguments:

localPath - local path of the desired mount folder

remotePath - remote path for the mount ex: /Google Drive/Pictures or just / for odrive root ex: odrive mount /my_local_sync_folder / unmount

Remove a mount usage: odrive unmount [-h] localPath positional arguments:

localPath - local path of the mount ex: odrive unmount /my_local_sync_folder backup

(Alpha feature. Can change or be removed at any time)

Backup a local folder to a remote odrive path usage: odrive backup [-h] localPath remotePath positional arguments:

localPath - local path of the desired backup folder

remotePath - remote path for the backup ex: /Dropbox/Backup ex: odrive backup /my_local_backup_folder /Dropbox/Backup removebackup

(Alpha feature. Can change or be removed at any time)

Remove a backup job usage: usage: odrive removebackup [-h] localPath positional arguments:

localPath - local path of the backup folder ex: odrive removebackup /my_local_backup_folder sync

Sync a placeholder folder or file usage: odrive sync [-h] placeholderPath [--recursive] [--nodownload] positional arguments:

placeholderPath - the path to the placeholder file optional arguments:

--recursive - recursively sync

--nodownload - do not download (used with --recursive) ex: odrive sync "/my_local_sync_folder/Dropbox.cloudf" --recursive --nodownload stream

(Alpha feature. Can change or be removed at any time)

Stream placholder/remote file usage: odrive stream [-h] path [--remote] positional arguments:

path - the path to the placeholder file or a remote path optional arguments:

--remote - use a remote path instead of a local placeholder path. ex: /Dropbox/movie.mp4 ex: odrive stream /Dropbox/movie.mp4 --remote | vlc - refresh

Refresh a folder usage: odrive refresh [-h] folderPath positional arguments:

folderPath - path of the local folder to refresh ex: odrive refresh /my_local_sync_folder/Dropbox unsync

Unsync a file or a folder to turn it back into a placeholder file usage: odrive unsync [-h] [--force] path positional arguments:

path - local file or folder to unsync optional arguments:

--force - force unsync a file or a folder - permanently deleting any local changes or files even if they have not been uploaded yet. ex: odrive unsync /my_local_sync_folder/Dropbox xlthreshold

Split files that are larger than this threshold into chunks usage: odrive xlthreshold [-h] {small,medium,large,xlarge} positional arguments:

{small,medium,large,xlarge} - choose from small(100MB), medium(500MB), large(1GB), xlarge(2GB) ex: odrive xlthreshold xlarge encpassphrase

Specify a passphrase for Encryptor folders usage: odrive encpassphrase [-h] [--initialize] passphrase id positional arguments:

passphrase - Encryptor folder passphrase

id - Encryptor ID. (When you first try to sync an Encryptor folder, the id will be given to you) optional arguments:

--initialize - Initialize a new Encryptor folder passphrase. Do not use this argument if the passphrase has already been set examples:

New folder: encpassphrase --initialize "mypassphrase" 11111111-1111-1111-1111-111111111111-11111111

Existing folder: encpassphrase "mypassphrase" 11111111-1111-1111-1111-111111111111-11111111 More information: https://forum.odrive.com/t/odrive-agent-releases-10-04-2018/5175 syncstate

Get sync status info usage: odrive syncstate [-h] [--textonly] path positional arguments:

path - file or folder path optional arguments:

--textonly - display file and folder states with text rather than color ex: odrive syncstate --textonly /my_local_sync_folder/Dropbox status

Get a summary of odrive's status usage: odrive status [-h] [--mounts | --backups | --sync_requests | --uploads | --downloads | --background | --trash | --waiting | --not_allowed] optional arguments:

--mounts - get status on mounts

--backups - get status on backup jobs

--sync_requests - get status on sync requests

--uploads - get status on uploads

--downloads - get status on downloads

--background - get status on background requests

--trash - get status of trash items

--waiting - get status of waiting items

--not_allowed - get status of not allowed items ex: odrive status deauthorize

Deauthorize odrive to disassociate the current user and exit usage: odrive deauthorize [-h] ex: odrive deauthorize diagnostics

Generate diagnostics. A local diagnostic file will be created at $HOME/.odrive-agent/current_odrive_status.txt usage: odrive diagnostics [-h] ex: odrive diagnostics emptytrash

Empty the contents of the odrive trash usage: odrive emptytrash [-h] ex: odrive emptytrash restoretrash

Restore the contents of the odrive trash usage: odrive restoretrash [-h] ex: odrive restoretrash shutdown

Shutdown/exit odrive usage: odrive shutdown [-h] ex: odrive shutdown

DOWNLOAD SYNC AGENT

odrive Sync Agent Service (Linux 32bit binary): https://dl.odrive.com/odriveagent-lnx-32

odrive Sync Agent Service (Linux 64bit binary): https://dl.odrive.com/odriveagent-lnx-64

odrive Sync Agent Service (OS X binary): https://dl.odrive.com/odriveagent-osx

odrive Sync Agent Service (Windows binary): https://dl.odrive.com/odriveagent-win

odrive Sync Agent service (RPi/ARMv6 binary): https://dl.odrive.com/odriveagent-rpi

DOWNLOAD CLI

odrive CLI (Python): https://dl.odrive.com/odrive-py

odrive CLI (Linux 32bit binary): https://dl.odrive.com/odrivecli-lnx-32

odrive CLI (Linux 64bit binary): https://dl.odrive.com/odrivecli-lnx-64

odrive CLI (OS X binary): https://dl.odrive.com/odrivecli-osx

odrive CLI (Windows binary): https://dl.odrive.com/odrivecli-win

odrive CLI (RPi/ARMv6 binary): https://dl.odrive.com/odrivecli-rpi

ADDITIONAL RESOURCES AND INFORMATION ADDITIONAL RESOURCES AND INFORMATION

Check out our in-depth blog post on the odrive CLI, including script examples

Visit our forum for more information and join the discussion