Agent/CLI (Linux, MacOS, Win)
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:
- Use a command like the following command in your terminal
nohup "$HOME/.odrive-agent/bin/odriveagent" > /dev/null 2>&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
andodrive_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 commandauthenticate
Authenticate odrive with an auth keyusage:
odrive authenticate [-h] authKey
positional arguments:
authKey - auth key from https://www.odrive.com/account/authcodesexample:
odrive authenticate 00000000-0000-0000-0000-000000000000-00000000
mount
Mount remote odrive path to the specified local folderusage:
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 rootex:
odrive mount /my_local_sync_folder /
unmount
Remove a mountusage:
odrive unmount [-h] localPath
positional arguments:
localPath - local path of the mountex:
odrive unmount /my_local_sync_folder
backup
Backup a local folder to a remote odrive pathusage:
odrive backup [-h] localPath remotePath
positional arguments:
localPath - local path of the desired backup folder
remotePath - remote path for the backup ex: /Dropbox/Backupex:
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 immediatelyusage:
odrive backupnow [-h]
ex:
odrive backupnow
removebackup
Remove a backup jobusage:
usage: odrive removebackup [-h] localPath
positional arguments:
localPath - local path of the backup folderex:
odrive removebackup /my_local_backup_folder
sync
Sync a placeholder folder or fileusage:
odrive sync [-h] placeholderPath [--recursive] [--nodownload]
positional arguments:
placeholderPath - the path to the placeholder fileoptional 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 folderusage:
odrive placeholderthreshold [-h] {never,small,medium,large,always}
positional arguments:
{never,small,medium,large,always} - choose from never, small(10MB), medium(100MB), large(500MB), alwaysex:
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 fileusage:
odrive unsync [-h] [--force] path
positional arguments:
path - local file or folder to unsyncoptional 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 timeusage:
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 fileusage:
odrive stream [-h] path [--remote]
positional arguments:
path - the path to the placeholder file or a remote pathoptional arguments:
--remote - use a remote path instead of a local placeholder path. ex: /Dropbox/movie.mp4ex:
odrive stream /Dropbox/movie.mp4 --remote | vlc -
refresh
Refresh a folderusage:
odrive refresh [-h] folderPath
positional arguments:
folderPath - path of the local folder to refreshex:
odrive refresh /my_local_sync_folder/Dropbox
xlthreshold
Split files that are larger than this threshold into chunksusage:
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 foldersusage:
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 setexamples:
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 infousage:
odrive syncstate [-h] [--textonly] path
positional arguments:
path - file or folder pathoptional arguments:
--textonly - display file and folder states with text rather than colorex:
odrive syncstate --textonly /my_local_sync_folder/Dropbox
status
Get a summary of odrive's statususage:
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 itemsex:
odrive status
deauthorize
Deauthorize odrive to disassociate the current user and exitusage:
odrive deauthorize [-h]
ex:
odrive deauthorize
diagnostics
Generate diagnostics. A local diagnostic file will be created at $HOME/.odrive-agent/current_odrive_status.txtusage:
odrive diagnostics [-h]
ex:
odrive diagnostics
emptytrash
Empty the contents of the odrive trashusage:
odrive emptytrash [-h]
ex:
odrive emptytrash
autotrashthreshold
Set rule for automatically emptying the odrive trashusage:
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 trashusage:
odrive restoretrash [-h]
ex:
odrive restoretrash
shutdown
Shutdown/exit odriveusage:
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:
- odrive Sync Agent Service (Linux 64bit binary) v1045: https://dl.odrive.com/odriveagent-lnx-64
- odrive Sync Agent Service (OS X binary) v977: https://dl.odrive.com/odriveagent-osx
- odrive Sync Agent Service (Windows binary) v976: https://dl.odrive.com/odriveagent-win
Older version from 11-04-2020 (newer release pending):
- odrive Sync Agent Service (Linux 32bit binary) v931: https://dl.odrive.com/odriveagent-lnx-32
- odrive Sync Agent service (RPi/ARMv6 binary) 32bit only v100: https://dl.odrive.com/odriveagent-rpi
DOWNLOAD CLI
Latest Version:
- odrive CLI (Python): https://dl.odrive.com/odrive-py
- odrive CLI (Linux 64bit binary) v1045: https://dl.odrive.com/odrivecli-lnx-64
- odrive CLI (OS X binary) v977: https://dl.odrive.com/odrivecli-osx
- odrive CLI (Windows binary) v976: https://dl.odrive.com/odrivecli-win
Older version from 11-04-2020 (newer release pending):
- odrive CLI (Linux 32bit binary) v931: https://dl.odrive.com/odrivecli-lnx-32
- odrive CLI (RPi/ARMv6 binary) 32bit only v100: https://dl.odrive.com/odrivecli-rpi
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 10 months ago