NAME

onedrive - A client for the Microsoft OneDrive Cloud Service

SYNOPSIS

onedrive [OPTION] --sync
onedrive [OPTION] --monitor
onedrive [OPTION] --display-config
onedrive [OPTION] --display-sync-status
onedrive [OPTION] -h | --help
onedrive --version

DESCRIPTION

A fully featured, free, and actively maintained Microsoft OneDrive client that seamlessly supports OneDrive Personal, OneDrive for Business, Microsoft 365 (formerly Office 365), and SharePoint document libraries.

Designed for maximum flexibility and reliability, this powerful and highly configurable client works across all major Linux distributions and FreeBSD. It can also be deployed in containerised environments using Docker or Podman. Supporting both one-way and two-way synchronisation modes, the client provides secure and efficient file syncing with Microsoft OneDrive services — tailored to suit both desktop and server environments.

FEATURES

* Compatible with OneDrive Personal, OneDrive for Business, and Microsoft SharePoint Libraries
* Provides full support for shared folders and files across both Personal and Business accounts
* Supports single-tenant and multi-tenant Microsoft Entra ID environments
* Supports national cloud deployments including Microsoft Cloud for US Government, Microsoft Cloud Germany, and Azure/Office 365 operated by VNET in China
* Supports bi-directional synchronisation (default) to keep local and remote data fully aligned
* Supports upload-only mode to upload local changes without downloading remote changes
* Supports download-only mode to download remote changes without uploading local changes
* Supports a dry-run mode for safely testing configuration changes without modifying data
* Implements safe conflict handling to minimise data loss by creating local backups when this is determined to be the safest resolution strategy
* Provides comprehensive rules-based client-side filtering with inclusions, exclusions, wildcard matching (*), and recursive globbing (**)
* Allows selective synchronisation of specific files, directories, or patterns
* Caches synchronisation state for efficient processing and improved performance on large or complex sync sets
* Supports near real-time processing of cloud-side changes using native WebSocket support
* Supports webhook-based online change notifications where WebSockets are unsuitable (manual configuration required)
* Monitors local file system changes in real-time using inotify
* Implements the FreeDesktop.org Trash specification, enabling recovery of files deleted locally due to remote deletions
* Protects against accidental data loss following configuration changes
* Supports interruption-tolerant uploads and downloads with automatic transfer resumption
* Validates file transfers to ensure data integrity
* Enhances synchronisation performance through multi-threaded file transfers
* Manages network usage through configurable bandwidth rate limiting
* Supports desktop notifications for synchronisation events, warnings, and errors using libnotify
* Provides desktop file-manager integration by registering the OneDrive folder as a sidebar location with a distinctive icon
* Operates fully in both graphical and headless/server environments, with a graphical environment required only for Intune SSO, desktop notifications, and sidebar integration

CONFIGURATION

By default, the OneDrive Client for Linux uses a sensible set of built-in defaults to interact with the Microsoft OneDrive service.

The client determines its configuration from three layers, applied in the following order of priority:

1. Application default values – internal defaults compiled into the client.
2. Configuration file values – user-defined settings loaded from a configuration file (if present).
3. Command-line arguments – values specified at runtime override both the configuration file and application defaults.

The built-in application defaults are sufficient for most users and provide a reliable operational baseline. Creating a configuration file or using command-line options is optional, and only required when you wish to customise runtime behaviour.

NOTE:

The OneDrive Client does not create a configuration file automatically. If no configuration file is found, the client runs entirely using its internally defined default values. You only need to create a configuration file if you wish to override those defaults.

If you want to adjust the default settings, download a copy of the default configuration template into your local configuration directory. Valid configuration file locations are:

~/.config/onedrive – for per-user configuration.
/etc/onedrive – for system-wide configuration.

Example:

To download a copy of the default configuration template, run:

mkdir -p ~/.config/onedrive
wget https://raw.githubusercontent.com/abraunegg/onedrive/v2.5.11/config -O ~/.config/onedrive/config

For a full list of configuration options and command-line switches, refer to the online documentation:
https://github.com/abraunegg/onedrive/blob/master/docs/application-config-options.md

CLIENT SIDE FILTERING

Client Side Filtering in the context of the OneDrive Client for Linux refers to user-configured rules that determine what files and directories the client should upload or download from Microsoft OneDrive. These rules are crucial for optimising synchronisation, especially when dealing with large numbers of files or specific file types. The OneDrive Client for Linux offers several configuration options to facilitate this:

--skip-dir or 'skip_dir' config file option

Specifies directories that should not be synchronised with OneDrive. Useful for omitting large or irrelevant directories from the sync process.

--skip-dot-files or 'skip_dotfiles' config file option

Excludes dotfiles, usually configuration files or scripts, from the sync. Ideal for users who prefer to keep these files local.

--skip-file or 'skip_file' config file option

Allows specifying specific files to exclude from synchronisation. Offers flexibility in selecting essential files for cloud storage.

--skip-symlinks or 'skip_symlinks' config file option

Prevents symlinks, which often point to files outside the OneDrive directory or to irrelevant locations, from being included in the sync.

Additionally, the OneDrive Client for Linux allows the implementation of Client Side Filtering rules through a 'sync_list' file. This file explicitly states which directories or files should be included in the synchronisation. By default, any item not listed in the 'sync_list' file is excluded. This approach offers granular control over synchronisation, ensuring that only necessary data is transferred to and from Microsoft OneDrive.

These configurable options and the 'sync_list' file provide users with the flexibility to tailor the synchronisation process to their specific needs, conserving bandwidth and storage space while ensuring that important files are always backed up and accessible.

NOTE:

After changing any Client Side Filtering rule, a full re-synchronisation must be performed using --resync

FIRST RUN

Once you've installed the application, you'll need to authorise it using your Microsoft OneDrive account. This can be done by simply running the application without any additional command switches.

Please be aware that some organisations may require administrator approval before this client can be used. If administrator consent is required, use --display-admin-consent-url to generate the appropriate Microsoft Entra ID administrator consent URL for your tenant.

When run for the first time in a supported graphical environment, the client will attempt to open the Microsoft authorisation URL in your default web browser and listen for the authorisation response on the local loopback callback address http://127.0.0.1:53100/. After you sign in and grant access, authentication should complete automatically and you may close the browser window.

If local browser authentication cannot be used, the client will fall back to the manual authentication flow. In that mode, open the displayed URL in your browser, sign in, grant access, then copy the full redirect URI from the browser address bar and paste it back into the application.

This process authenticates the application with your account information, after which the client is ready to sync your data between your local system and Microsoft OneDrive.

GUI NOTIFICATIONS

If the client has been compiled with support for notifications, the client will send notifications about client activity via libnotify to the GUI via DBus when the client is being run in --monitor mode.

APPLICATION LOGGING

When running onedrive all actions can be logged to a separate log file. This can be enabled by using the --enable-logging flag. By default, log files will be written to /var/log/onedrive. All logfiles will be in the format of %username%.onedrive.log, where %username% represents the user who ran the client.

ALL CLI OPTIONS

The options below allow you to control the behaviour of the onedrive client from the CLI. Without any specific option, if the client is already authenticated, the client will exit without any further action.

--sync, -s

Do a one-time synchronisation with Microsoft OneDrive.

--monitor, -m

Monitor filesystem and synchronise regularly with Microsoft OneDrive.

--display-config

Display the currently used configuration for the onedrive client.

--display-sync-status

Query OneDrive service and report on pending changes.

--auth-files ARG

Perform authentication not via interactive dialogue but via files that are read/written when using this option. The two files are passed in as ARG in the format authUrl:responseUrl. The authorisation URL is written to the authUrl file, then onedrive waits for the file responseUrl to be present, and reads the response from that file.
Always specify the full path when using this option, otherwise the application will default to using the default configuration path for these files (~/.config/onedrive/)

--auth-response ARG

Perform authentication not via interactive dialogue but via providing the response URL directly.

--check-for-nomount

Check for the presence of .nosync in the syncdir root. If found, do not perform sync.

--check-for-nosync

Check for the presence of .nosync in each directory. If found, skip directory from sync.

--classify-as-big-delete ARG

Number of children in a path that is locally removed which will be classified as a 'big data delete'.

--cleanup-local-files

Clean up additional local files when using --download-only. This will remove local data.

--confdir ARG

Set the directory used to store the configuration files.

--create-directory ARG

Create a directory on OneDrive. No synchronisation will be performed.

--create-share-link ARG

Create a shareable link for an existing file on OneDrive.
Use --with-editing-perms to create a read-write share link instead of read-only.
Use --share-password <password> to protect the shared link with a password.

--debug-https

Debug OneDrive HTTPS communication.

--destination-directory ARG

Destination directory for renamed or moved items on OneDrive. No synchronisation will be performed.

--disable-download-validation

Disable download validation when downloading from OneDrive.

--disable-notifications

Do not use desktop notifications in monitor mode.

--disable-upload-validation

Disable upload validation when uploading to OneDrive.

--display-admin-consent-url

Displays a tenant-specific Microsoft Entra ID administrator consent URL for environments where administrator approval is required before users can authenticate and use the client.

--display-quota

Display the quota status of the client. No synchronisation will be performed.

--download-file ARG

Download a single file from Microsoft OneDrive.
Specify the full online path to the file. No synchronisation will be performed.

--display-running-config

Display what options the client has been configured to use on application startup.

--download-only

Replicate the OneDrive online state locally, by only downloading changes from OneDrive. Do not upload local changes to OneDrive.

--dry-run

Perform a trial sync with no changes made.

--enable-logging

Enable client activity to a separate log file.

--file-fragment-size ARG

Specify the file fragment size for large file uploads (in MB).

--force

Force the deletion of data when a 'big delete' is detected.

--force-http-11

Force the use of HTTP 1.1 for all operations.

--force-sync

Force a synchronisation of a specific folder, only when using --sync --single-directory and ignore all non-default skip_dir and skip_file rules.

--get-file-link ARG

Display the file link of a synced file.

--get-sharepoint-drive-id ARG

Query and return the Microsoft 365 Drive ID for a given SharePoint document library.

--help, -h

Display application help.

--list-shared-items

List OneDrive Business Shared Items.

--local-first

Synchronise from the local directory source first, before downloading changes from OneDrive.

--log-dir ARG

Directory where logging output is saved to, needs to end with a slash.

--logout

Log out the current user.

--mirror-local-state

When used with --local-first, removes remote-only files and directories from Microsoft OneDrive to make the online state match the local filesystem.

--modified-by ARG

Display the last modified by details of a given path.

--monitor-fullscan-frequency ARG

Number of scheduled monitor-interval sync cycles before performing an online full-scan true-up. This does not disable the local database consistency check.

--monitor-interval ARG

Number of seconds by which each sync operation is undertaken when idle under monitor mode.

--monitor-log-frequency ARG

Frequency of logging in monitor mode.

--no-remote-delete

Do not delete local file 'deletes' from OneDrive when using --upload-only.

--print-access-token

Print the access token, useful for debugging.

--reauth

Reauthenticate the client with OneDrive.

--remove-directory ARG

Remove a directory on OneDrive. No synchronisation will be performed.

--remove-source-files

Remove source file after successful transfer to OneDrive when using --upload-only.

--remove-source-folders

Remove the local directory structure post successful file transfer to Microsoft OneDrive when using --upload-only --remove-source-files.

--resync

Forget the last saved state, perform a full sync.

--resync-auth

Approve the use of performing a --resync action.

--share-password ARG

Require a password to access the shared link when used with --create-share-link <file>. Only supported for OneDrive Business and SharePoint environments that permit password-protected sharing.

--single-directory ARG

Specify a single local directory within the OneDrive root to sync.

--skip-dir ARG

Skip any directories that match this pattern from syncing.

--skip-dir-strict-match

When matching skip_dir directories, only match explicit matches.

--skip-dot-files

Skip dot files and folders from syncing.

--skip-file ARG

Skip any files that match this pattern from syncing.

--skip-size ARG

Skip new files larger than this size (in MB).

--skip-symlinks

Skip syncing of symlinks.

--source-directory ARG

Source directory to rename or move on OneDrive. No synchronisation will be performed.

--space-reservation ARG

The amount of disk space to reserve (in MB) to avoid 100% disk space utilisation.

--sync-root-files

Sync all files in sync_dir root when using sync_list.

--sync-shared-files

Sync OneDrive Business Shared Files to the local filesystem.

--syncdir ARG

Specify the local directory used for synchronisation to OneDrive.

--threads ARG

Specify a value for the number of worker threads used for parallel upload and download operations.

--upload-only

Replicate the locally configured sync_dir state to OneDrive, by only uploading local changes to OneDrive. Do not download changes from OneDrive.

--verbose, -v+

Print more details, useful for debugging (repeat for extra debugging).

--version

Print the version and exit.

--with-editing-perms

Create a read-write shareable link for an existing file on OneDrive when used with --create-share-link <file>.

DOCUMENTATION

All documentation is available on GitHub: https://github.com/abraunegg/onedrive/tree/master/docs/

SEE ALSO

curl(1)