odrive

The odrive Developer Hub

Welcome to the odrive developer hub. You'll find comprehensive guides and documentation to help you start working with odrive as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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/

(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 &

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:

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


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


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

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
(Beta feature)
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.


removebackup
(Beta feature)
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

DOWNLOAD CLI



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 19 days ago

Agent/CLI (Linux, MacOS, Win)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.