Guides
Guides

Agent/CLI (Linux, MacOS, Win)

Suggest Edits

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 (32bit) 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

Please note: The ARM builds are 32bit only. We apologize for any inconvenience this may cause.

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.

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/

To run the odrive agent:
$HOME/.odrive-agent/bin/odriveagent

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

  1. Use a command like the following command in your terminal
nohup "$HOME/.odrive-agent/bin/odriveagent" > /dev/null 2>&1 &
  1. Create a systemd user service like the provided example:

📘

# systemd user service to run odrive agent
#
# Use loginctl enable-linger to create a user manager for the user at boot and kept around after logouts. This will allow auto-starting of the odrive agent for that user
# https://www.freedesktop.org/software/systemd/man/loginctl.html#enable-linger%20USER%E2%80%A6
#
# save this file as:
# ~/.config/systemd/user/odrive.service
#
# enable: $ systemctl --user enable odrive.service 
# start:  $ systemctl --user start odrive.service 
# status: $ systemctl --user status odrive.service
# 

[Unit]
Description=Run odrive-agent as a user service
Wants=network-online.target
After=network.target network-online.target

[Service]
Type=simple
ExecStart=%h/.odrive-agent/bin/odriveagent
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
# https://www.freedesktop.org/software/systemd/man/systemd.special.html#Units%20managed%20by%20the%20user%20service%20manager

🚧

The odrive agent will store its database and configuration files in the running user's home/profile directory inside a directory named .odrive-agent. The instructions above use this directory as an example of where to store the binaries, which keeps everything in one place, but regardless of where you store and run the binaries, the odrive agent will expect the $HOME/.odrive-agent directory to be accessible and writable for the user that is executing the process.

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:

"$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:

"$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  

$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:

Start-Job { & "$HOME\.odrive-agent\bin\odriveagent.exe" }

You can also just run the command normally.
ex: $HOME/.odrive-agent/bin/odriveagent

📘

The odrive agent will store its database and configuration files in the running user's home/profile directory inside a directory named .odrive-agent. The instructions above use this directory as an example of where to store the binaries, which keeps everything in one place, but regardless of where you store and run the binaries, the odrive agent will expect the $HOME/.odrive-agent directory to be accessible and writable for the user that is executing the process.

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:

& "$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:

& "$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.

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:

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

📘

The odrive agent will store its database and configuration files in the running user's home/profile directory inside a directory named .odrive-agent. The instructions above use this directory as an example of where to store the binaries, which keeps everything in one place, but regardless of where you store and run the binaries, the odrive agent will expect the $HOME/.odrive-agent directory to be accessible and writable for the user that is executing the process.

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:

"$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:

"$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]

"$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

📘

Logging and advanced settings

A detailed sync log is available at $HOME/.odrive-agent/log/main.log.

Advanced client options are configurable from the odrive_user_general_conf.txt and odrive_user_premium_conf.txt files, located in $HOME/.odrive-agent/

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.

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.

"$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) 

"$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]

"$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
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

Note: The backup interval can be adjusted via the odrive advanced configuration files
The default backup interval is 24 hours.

backupnow
Run backup jobs immediately

usage: odrive backupnow [-h]

ex: odrive backupnow

removebackup
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

placeholderthreshold
Set rule for automatically downloading files under a specified size when syncing/expanding a folder

usage: odrive placeholderthreshold [-h] {never,small,medium,large,always}

positional arguments:
{never,small,medium,large,always} - choose from never, small(10MB), medium(100MB), large(500MB), always

ex: odrive placeholderthreshold small

foldersyncrule
Set rule for automatically syncing new remote content. This is usually used after recursively syncing a folder.

usage: odrive foldersyncrule [-h] [--expandsubfolders] path threshold

positional arguments:
path - The local path of the folder to apply the rule to.
threshold - Size in MB (base 10) for the download threshold. Use '0' for nothing and 'inf' for infinite. Files that have a size under this will be downloaded.

optional arguments:
--expandsubfolders Apply this rule to files and folders underneath the specified folder.

ex: odrive foldersyncrule "/my_local_sync_folder/Dropbox" 100 --expandsubfolders

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

autounsyncthreshold
Set rule for automatically unsyncing files that have not been modified with a certain amount of time

usage: odrive autounsyncthreshold [-h] {never,day,week,month}

positional arguments:
{never,day,week,month} - choose from never, daily (day), weekly (week), monthly (month)

ex: odrive autounsyncthreshold month

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

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

autotrashthreshold
Set rule for automatically emptying the odrive trash

usage: odrive autotrashthreshold[-h] {never,immediately,fifteen,hour,day}

positional arguments:
{never,immediately,fifteen,hour,day} - choose from never, immediately, every fifteen minutes (fifteen), hourly (hour), daily (day)

ex: odrive autotrashhreshold day

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

LOGGING AND ADVANCED SETTINGS

A detailed sync log is available at $HOME/.odrive-agent/log/main.log.

Advanced client options are configurable from the odrive_user_general_conf.txt and odrive_user_premium_conf.txt files, located in $HOME/.odrive-agent/

DOWNLOAD SYNC AGENT

Latest Version:

Older version from 11-04-2020 (newer release pending):

DOWNLOAD CLI

Latest Version:

Older version from 11-04-2020 (newer release pending):

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

Updated 9 months ago