onedrive/docs/usage.md

Using the OneDrive Client for Linux

Application Version

Before reading this document, please ensure you are running application version or greater. Use onedrive --version to determine what application version you are using and upgrade your client if required.

Table of Contents

• Important Notes

  • Memory Usage
  • Large OneDrive Accounts and Item Counts
  • Guidelines for Local File and Folder Naming in the Synchronisation Directory
  • Support for Microsoft Azure Information Protected Files
  • Compatibility with Editors and Applications Using Atomic Save Operations
  • Compatibility with Obsidian
  • Compatibility with curl

• First Steps

  • Authorise the Application with Your Microsoft OneDrive Account
  • Display Your Applicable Runtime Configuration
  • Understanding OneDrive Client for Linux Operational Modes
    • Standalone Synchronisation Operational Mode (Standalone Mode)
    • Ongoing Synchronisation Operational Mode (Monitor Mode)
      • Machine-readable monitor runtime status

• Using the OneDrive Client for Linux to synchronise your data

  • Client Documentation
  • Increasing application logging level
  • Using 'Client Side Filtering' rules to determine what should be synced with Microsoft OneDrive
  • Why 'Server Side Filtering' is not possible with Microsoft OneDrive
  • Testing your configuration
  • Performing a sync with Microsoft OneDrive
  • Performing a single directory synchronisation with Microsoft OneDrive
  • Performing a 'one-way' download synchronisation with Microsoft OneDrive
  • Performing a 'one-way' upload synchronisation with Microsoft OneDrive
  • Performing a selective synchronisation via 'sync_list' file
  • Checking synchronisation status without performing a sync
  • Performing a --resync
  • Performing a --force-sync without a --resync or changing your configuration
  • Enabling the Client Activity Log
    • Client Activity Log Example:
    • Client Activity Log Differences
  • Display Manager Integration
  • GUI Notifications
  • Using a local Recycle Bin
  • Handling a Microsoft OneDrive Account Password Change
  • Determining the synchronisation result
  • Resumable Transfers

• Frequently Asked Configuration Questions

  • How to change the default configuration of the client?
  • How to change where my data from Microsoft OneDrive is stored?
  • How do I safely remove my local sync_dir without deleting my OneDrive data?
  • Why does the client create 'safeBackup' files?
  • How to change what file and directory permissions are assigned to data that is downloaded from Microsoft OneDrive?
  • How are uploads and downloads managed?
  • How to only sync a specific directory?
  • How to 'skip' files from syncing?
  • How to 'skip' directories from syncing?
  • How to 'skip' .files and .folders from syncing?
  • How to 'skip' files larger than a certain size from syncing?
  • How to 'rate limit' the application to control bandwidth consumed for upload & download operations?
  • How can I prevent my local disk from filling up?
  • How does the client handle symbolic links?
  • How to synchronise OneDrive Personal Shared Folders?
  • How to synchronise OneDrive Business Shared Items (Files and Folders)?
  • How to synchronise SharePoint / Office 365 Shared Libraries?
  • How to Create a Shareable Link?
  • How to Synchronise Both Personal and Business Accounts at once?
  • How to Synchronise Multiple SharePoint Libraries simultaneously?
  • How to Receive Real-time Changes from Microsoft OneDrive Service, instead of waiting for the next sync period?
  • How to initiate the client as a background service?
    • Choosing a systemd service
    • Running OneDrive as a non-root user with a systemd system service
    • Running OneDrive with a systemd user service
    • Microsoft Intune SSO and systemd startup
    • OneDrive service running as root user via init.d
    • OneDrive service running as a non-root user via runit (antiX, Devuan, Artix, Void)
  • Running the systemd user service without login (lingering)
  • How to access Microsoft OneDrive service through a proxy
  • How to set up SELinux for a sync folder outside of the home folder
  • Why do I see Performing a database consistency and integrity check on locally stored data every monitor cycle?

• Advanced Configuration of the OneDrive Client for Linux

• Overview of all OneDrive Client for Linux CLI Options

Important Notes

Memory Usage

The amount of memory used by the OneDrive Client depends on several factors, including the number of objects stored online, the type of synchronisation being performed, the amount of metadata returned by Microsoft OneDrive, configured filtering rules, and any concurrent upload or download activity.

Starting with version 2.5.12, large online enumerations are processed using bounded working sets rather than retaining the complete set of retrieved objects in memory before processing begins. This significantly reduces the memory required for large OneDrive accounts during operations such as an initial synchronisation, --resync, Full Scan reconciliation and other authoritative online scans.

In monitor mode, the application also performs managed-memory collection and heap minimisation after each completed monitor loop. This allows temporary objects created during synchronisation to be reclaimed promptly and unused managed heap capacity to be returned to the operating system where possible.

Important

Resident Set Size (RSS) does not directly represent the amount of application data that is currently in use.

The D runtime, system allocator, SQLite, curl and other native libraries may retain previously allocated memory for later reuse. As a result, RSS may remain above its initial value even after temporary synchronisation data has been released.

For a long-running monitor process, the important behaviour is that memory reaches a bounded working level and is subsequently reused, rather than increasing continuously after each synchronisation or Full Scan.

The previous guidance for early 2.5.x releases that suggested allowing approximately 1 GB of memory for every 100,000 OneDrive objects is no longer applicable to version 2.5.12 and later.

As part of the version 2.5.12 memory and large-account validation, the client was repeatedly tested against a fixed dataset containing 101,494 OneDrive objects. In these controlled tests, both the normal Microsoft Graph /delta pathway and the generated /children pathway demonstrated bounded memory behaviour over repeated authoritative scans rather than memory usage increasing in proportion to each scan.

These results are validation data rather than a guaranteed memory requirement. Actual memory consumption will vary depending on platform, compiler/runtime, account contents, enabled features and workload.

When diagnosing memory behaviour, the developer option:

display_memory = "true"

can be enabled to display memory information at each monitor-loop collection boundary.

The reported values include:

• usedSize — managed heap memory currently containing live allocations.
• freeSize — managed heap capacity currently reserved and available for reuse.
• allocatedInCurrentThread — a cumulative allocation counter. This value will continually increase while the application runs and does not represent current memory usage.
• Resident Set Size (RSS) — memory currently resident in the process according to the operating system, including managed and native allocations.

When investigating a suspected memory issue, trends across multiple monitor loops and Full Scans are more meaningful than any individual RSS reading.

Large OneDrive Accounts and Item Counts

Microsoft has historically recommended synchronising no more than 300,000 items for optimal performance with its OneDrive sync application. Microsoft has also introduced public-preview support for up to 1,000,000 items on eligible Windows and macOS clients, subject to Microsoft's requirements. This expanded capability does not establish a new Microsoft Graph API item-count limit or a support guarantee for third-party clients. Refer to Microsoft's OneDrive and SharePoint restrictions and limitations for current guidance.

The OneDrive Client for Linux does not impose a corresponding 300,000-item synchronisation limit. However, Microsoft's expanded official-client capability should not be interpreted as validation that this client can reliably synchronise 1,000,000 items. Large-account performance depends on available resources, online enumeration, Microsoft Graph throttling, synchronisation mode and the configured filtering rules.

Version 2.5.12 includes the large-account memory improvements described in Memory Usage. The controlled 101,494-object validation described above is evidence of improved memory behaviour, not a certified maximum item count or a guarantee of performance at higher counts.

Guidelines for Local File and Folder Naming in the Synchronisation Directory

To ensure seamless synchronisation with Microsoft OneDrive, it's critical to adhere strictly to the prescribed naming conventions for your files and folders within the sync directory. The guidelines detailed below are designed to preempt potential sync failures by aligning with Microsoft Windows Naming Conventions, coupled with specific OneDrive restrictions.

Warning

Failure to comply will result in synchronisation being bypassed for the offending files or folders, necessitating a rename of the local item to establish sync compatibility.

Key Restrictions and Limitations

• Invalid Characters:
  • Avoid using the following characters in names of files and folders: " * : < > ? / \ |
  • Names should not start or end with spaces
  • Names should not end with a fullstop / period character .
• Prohibited Names:
  • Certain names are reserved and cannot be used for files or folders: .lock, CON, PRN, AUX, NUL, COM0 - COM9, LPT0 - LPT9, desktop.ini, any filename starting with ~$
  • The text sequence _vti_ cannot appear anywhere in a file or directory name
  • A file and folder called forms is unsupported at the root level of a synchronisation directory
• Path Length
  • All files and folders stored in your 'sync_dir' (typically ~/OneDrive) must not have a path length greater than:
    • 400 characters for OneDrive Business & SharePoint
    • 430 characters for OneDrive Personal

Should a file or folder infringe upon these naming conventions or restrictions, synchronisation will skip the item, indicating an invalid name according to Microsoft Naming Convention. The only remedy is to rename the offending item. This constraint is by design and remains firm.

Tip

The UTF-16 character set provides a capability to use alternative characters to work around the restrictions and limitations imposed by Microsoft OneDrive. An example of some replacement characters are below:

Standard Invalid Character	Potential UTF-16 Replacement Character
.	․ (One Dot Leader, \u2024)
:	ː (Modifier Letter Triangular Colon, \u02D0)
|	│ (Box Drawings Light Vertical, \u2502)

Caution

The last critically important point is that Microsoft OneDrive does not adhere to POSIX standards, which fundamentally impacts naming conventions. In Unix environments (which are POSIX compliant), files and folders can exist simultaneously with identical names if their capitalisation differs. This is not possible on Microsoft OneDrive. If such a scenario occurs, the OneDrive Client for Linux will encounter a conflict, preventing the synchronisation of the conflicting file or folder. This constraint is a conscious design choice and is immutable. To avoid synchronisation issues, preemptive renaming of any conflicting local files or folders is advised.

Further reading:

The above guidelines are essential for maintaining synchronisation integrity with Microsoft OneDrive. Adhering to them ensures your files and folders sync without issue. For additional details, consult the following resources:

• Microsoft Windows Naming Conventions
• Restrictions and limitations in OneDrive and SharePoint

Adherence to these guidelines is not optional but mandatory to avoid sync disruptions.

Support for Microsoft Azure Information Protected Files

Caution

If you are using OneDrive Business Accounts and your organisation implements Azure Information Protection, these AIP files will report as one size & hash online, but when downloaded, will report a totally different size and hash. This is due to how the Microsoft Graph API handles AIP files and how Microsoft SharePoint (the technology behind Microsoft OneDrive for Business) serves these files via the API.

By default these files will fail integrity checking and be deleted locally, meaning that AIP files will not reside on your platform. These AIP files will be flagged as a failed download during application operation.

If you chose to enable --disable-download-validation , the AIP files will download to your platform, however, if there are any other genuine download failures where the size and hash are different, these too will be retained locally meaning you may experience data integrity loss. This is due to the Microsoft Graph API lacking any capability to identify up-front that a file utilises AIP, thus zero capability to differentiate between AIP and non-AIP files for failure detection.

Please use the --disable-download-validation option with extreme caution and understand the risk if you enable it.

Compatibility with Editors and Applications Using Atomic Save Operations

Many modern editors and applications—including vi, vim, nvim, emacs, LibreOffice, Obsidian and others—use atomic save strategies to preserve data integrity when writing files. This section outlines how such operations interact with the onedrive client, what users can expect, and why certain side effects (such as editor warnings or perceived timestamp discrepancies) may occur.

How Atomic Save Operations Work

When these applications save a file, they typically follow this sequence:

1. Create a Temporary File
   A new file is written with the updated content, often in the same directory as the original.

2. Flush to Disk
   The temporary file is flushed to disk using fsync() or an equivalent method to ensure data safety.

3. Atomic Rename
   The temporary file is renamed to the original filename using the rename() syscall.
   This is an atomic operation on Linux, meaning the original file is replaced, not modified.

4. Remove Lock or Swap Files
   Auxiliary files used during editing (e.g., .swp, .#filename) are deleted.

As a result, the saved file is technically a new file with a new inode and a new timestamp, even if the filename remains unchanged.

How This Affects the OneDrive Client

When the onedrive client observes such an atomic save operation via inotify, it detects:

• The original file as deleted.
• A new file (with the same name) as created.

The client responds accordingly:

• The "new" file is uploaded to Microsoft OneDrive.
• After upload, Microsoft assigns its own modification timestamp to the file.
• To ensure consistency between local and remote states, the client updates the local file’s timestamp to match the exact time stored in OneDrive.

Important

Microsoft OneDrive does not support fractional-second precision in file timestamps—only whole seconds. As a result, small discrepancies may occur if the local file system supports higher-resolution timestamps.

This behaviour ensures accurate syncing and content integrity, but may lead to subtle side effects in timestamp-sensitive applications.

Expected Side Effects

• Timestamp Alignment for Atomic Saves
  Editors that rely on local file timestamps (rather than content checksums) can issue warnings that a file had changed unexpectedly—typically because the onedrive client potentially updated the modification time after upload. This client attempts to preserve the original modification timestamp only if fractional seconds differ, preventing unnecessary local timestamp changes. As a result, editors such as vi, vim, nvim, emacs, LibreOffice and Obsidian should not trigger warnings when saving files using atomic operations.

• False Conflict Prompts (Collaborative Editing)
  In collaborative editing scenarios—such as with LibreOffice or shared OneDrive folders—conflict prompts may still occur if another user or device modifies a file, resulting in a meaningful timestamp or content change.
  However, for local edits using atomic save methods, the client now avoids unnecessary timestamp updates, effectively eliminating false conflicts in those cases.

Recommendation

If you are using editors that rely on strict timestamp semantics and wish to minimise interference from the onedrive client:

• Save your work, then pause or temporarily stop sync (onedrive --monitor).
• Resume syncing when finished.
• Configure the client to ignore temporary files your editor uses via the skip_file setting if they do not need to be synced.
• Configure the client to use 'session uploads' for all files via the force_session_upload setting. This option, when enabled, forces the client to use a 'session' upload, which, when the 'file' is uploaded by the session, this includes the actual local timestamp (without fractional seconds) of the file that Microsoft OneDrive should store.

Summary

The onedrive client is fully compatible with applications that use atomic save operations. Users should be aware that:

• Atomic saves result in the file being treated as a new item.
• Timestamps may be adjusted post-upload to match OneDrive's stored value.
• In rare cases, timestamp-sensitive applications may display warnings or prompts.

This behaviour is by design and ensures consistency and data integrity between your local filesystem and the OneDrive cloud.

Compatibility with Obsidian

Obsidian on Linux does not provide a built-in way to disable atomic saves or switch to a backup-copy method via configuration. The application is built on Electron and relies on the default save behaviour of its underlying libraries and editor components (such as CodeMirror), which typically perform atomic writes using the following process:

1. A temporary file is created containing the updated content.
2. That temporary file is flushed to disk.
3. The temporary file is atomically renamed to replace the original file.

This behaviour is intended to improve data integrity and crash resilience, but it results in high disk I/O — particularly in Obsidian, where auto-save is triggered nearly every keystroke.

Important

Obsidian provides no mechanism to change how this save behaviour operates. This is a serious design limitation and should be treated as a bug in the application. The excessive and unnecessary write operations can significantly reduce the lifespan of SSDs over time due to increased wear, leading to broader consequences for system reliability.

How This Affects the OneDrive Client

Because Obsidian is constantly writing files, running the OneDrive Client for Linux in --monitor mode causes the client to continually receive inotify events from the local file system. This leads to constant re-uploading of files, regardless of whether meaningful content has changed.

The consequences of this are:

1. Continuous upload attempts to Microsoft OneDrive.
2. Potential for repeated overwrites of online data.
3. Excessive API usage, which may result in Microsoft throttling your access — subsequently affecting the client’s ability to synchronise files reliably.

Recommendation

If you use Obsidian, it is strongly recommended that you enable the following two configuration options in your OneDrive Client for Linux config file:

force_session_upload = "true"
delay_inotify_processing = "true"

These settings introduce a delay in processing local file change events, allowing the OneDrive Client for Linux to batch or debounce Obsidian's frequent writes. By default, this delay is 5 seconds.

To adjust this delay, you can add the following configuration option:

inotify_delay = "10"

This example sets the delay to 10 seconds.

Caution

Increasing inotify_delay too aggressively may have unintended side effects. All file system events are queued and processed in order, so setting a very high delay could result in large backlogs or undesirable data synchronisation outcomes — particularly in cases of rapid file changes or deletions.

Adjust this setting with extreme caution and test thoroughly to ensure it does not impact your workflow or data integrity.

Tip

An Obsidian Plugin also exists to 'control' the auto save behaviour of Obsidian.

Instead of saving every two seconds from start of typing (Obsidian default), this plugin makes Obsidian wait for the user to finish with editing, and after the input stops, it waits for a defined time (by default 10 seconds) and then it only saves once.

For more information please read: https://github.com/mihasm/obsidian-autosave-control

Compatibility with curl

If your system uses curl < 7.47.0, curl will default to HTTP/1.1 for HTTPS operations, and the client will follow suit, using HTTP/1.1.

For systems running curl >= 7.47.0 and < 7.62.0, curl will prefer HTTP/2 for HTTPS, but it will still use HTTP/1.1 as the default for these operations. The client will employ HTTP/1.1 for HTTPS operations as well.

However, if your system employs curl >= 7.62.0, curl will, by default, prioritise HTTP/2 over HTTP/1.1. In this case, the client will utilise HTTP/2 for most HTTPS operations and stick with HTTP/1.1 for others. Please note that this distinction is governed by the OneDrive platform, not our client.

If you explicitly want to use HTTP/1.1, you can do so by using the --force-http-11 flag or setting the configuration option force_http_11 = "true". This will compel the application to exclusively use HTTP/1.1. Otherwise, all client operations will align with the curl default settings for your distribution.

Known curl bugs that impact the use of this client

id	curl bug	fixed in curl version
1	HTTP/2 support: Introduced HTTP/2 support, enabling multiplexed transfers over a single connection	7.47.0
2	HTTP/2 issue: Resolved an issue where HTTP/2 connections were not properly reused, leading to unnecessary new connections.	7.68.0
3	HTTP/2 issue: Addressed a race condition in HTTP/2 multiplexing that could lead to unexpected behaviour.	7.74.0
4	HTTP/2 issue: Improved handling of HTTP/2 priority frames to ensure proper stream prioritisation.	7.81.0
5	HTTP/2 issue: Fixed a bug where HTTP/2 connections were prematurely closed, resulting in incomplete data transfers.	7.88.1
6	HTTP/2 issue: Resolved a problem with HTTP/2 frame handling that could cause data corruption during transfers.	8.2.1
7	HTTP/2 issue: Corrected an issue where HTTP/2 streams were not properly closed, leading to potential memory leaks.	8.5.0
8	HTTP/2 issue: Addressed a bug where HTTP/2 connections could hang under specific conditions, improving reliability.	8.8.0
9	HTTP/2 issue: Improved handling of HTTP/2 connections to prevent unexpected stream resets and enhance stability.	8.9.0
10	SIGPIPE issue: Resolved a problem where SIGPIPE signals were not properly handled, leading to unexpected behaviour.	8.9.1
11	SIGPIPE issue: Addressed a SIGPIPE leak that occurred in certain cases starting with version 8.9.1	8.10.0
12	HTTP/2 issue: Stopped offering ALPN http/1.1 for http2-prior-knowledge to ensure proper protocol negotiation.	8.10.0
13	HTTP/2 issue: Improved handling of end-of-stream (EOS) and blocked states to prevent unexpected behaviour.	8.11.0
14	OneDrive operation encountered an issue with libcurl reading the local SSL CA Certificates issue	8.14.1

Known curl versions with compatibility issues for this client

curl Version	distribution	curl bugs
7.68.0	Ubuntu 20.04 LTS (Focal Fossa)	2,3,4,5,6,7,8,9,10,11,12,13
7.74.0	Debian 11 (Bullseye)	4,5,6,7,8,9,10,11,12,13
7.81.0	Ubuntu 22.04 LTS (Jammy Jellyfish)	5,6,7,8,9,10,11,12,13
7.88.1	Debian 12 (Bookworm)	6,7,8,9,10,11,12,13
8.2.1	Alpine Linux 3.14	7,8,9,10,11,12,13
8.5.0	Alpine Linux 3.15, Ubuntu 24.04 LTS (Noble Numbat)	8,9,10,11,12,13
8.9.1	Ubuntu 24.10 (Oracular Oriole)	11,12,13
8.10.0	Alpine Linux 3.17	13
8.13.0	Various + Self Compiled	14
8.13.1	Various + Self Compiled	14
8.14.0	Various + Self Compiled	14

Important

If your distribution provides one of these curl versions you must upgrade your curl version to the latest available, or get your distribution to provide a more modern version of curl. Refer to curl releases for curl version information.

If you are using one of the above curl versions, the following application message will be generated:

WARNING: Your curl/libcurl version (curl.version.number) has known HTTP/2 bugs that impact the use of this application.
         Please report this to your distribution and request that they provide a newer curl version for your platform or upgrade this yourself.
         Downgrading all application operations to use HTTP/1.1 to ensure maximum operational stability.
         Please read https://github.com/abraunegg/onedrive/blob/master/docs/usage.md#compatibility-with-curl for more information.

The WARNING line will be sent to the GUI for notification purposes if notifications have been enabled. To avoid this message and/or the GUI notification your only have 2 options:

1. Upgrade your curl version on your platform
2. Configure the client to always downgrade client operations to HTTP/1.1 and use IPv4 only

If you are unable to upgrade your version of curl, to always downgrade client operations to HTTP/1.1 you must add the following to your config file:

force_http_11 = "true"
ip_protocol_version = "1"

When these two options are applied to your application configuration, the following application message will be generated:

WARNING: Your curl/libcurl version (curl.version.number) has known operational bugs that impact the use of this application.
         Please report this to your distribution and request that they provide a newer curl version for your platform or upgrade this yourself.

The WARNING line will be now only be written to application logging output, no longer sending a GUI notification message.

Important

Outside of the above known broken curl versions, there are significant HTTP/2 bugs in all curl versions < 8.6.x that can lead to HTTP/2 errors such as Error in the HTTP2 framing layer on handle or Stream error in the HTTP/2 framing layer on handle

The only options to resolve this issue are the following:

1. Upgrade your curl version to the latest available, or get your distribution to provide a more modern version of curl. Refer to curl releases for curl version information.
2. Configure the client to only use HTTP/1.1 via the config option --force-http-11 flag or set the configuration file option force_http_11 = "true"

Important

Outside of the above known broken curl versions, it has also been evidenced that curl has an internal DNS resolution bug that at random times will skip using IPv4 for DNS resolution and only uses IPv6 DNS resolution when the host system is configured to use IPv4 and IPv6 addressing.

As a result of this internal curl resolution bug, if your system does not have an IPv6 DNS resolver, and/or does not have a valid IPv6 network path to Microsoft OneDrive, you may encounter these errors:

• A libcurl timeout has been triggered - data transfer too slow, no DNS resolution response, no server response
• Could not connect to server on handle ABC12DEF3456

The only options to resolve this issue are the following:

1. Implement and/or ensure that IPv6 DNS resolution is possible on your system; allow IPv6 network connectivity between your system and Microsoft OneDrive
2. Configure the client to only use IPv4 DNS resolution via setting the configuration option ip_protocol_version = "1"

Important

If you are using Debian 12 or Linux Mint Debian Edition (LMDE) 6, you can install the latest curl version from the respective backports repositories to address the bugs present in the default Debian 12 curl version.

Caution

If you continue to use a curl/libcurl version with known HTTP/2 bugs the application will automatically downgrade HTTP operations to HTTP/1.1, however you will continue to experience application runtime issues such as randomly exiting for zero reason or incomplete download/upload of your data.

First Steps

Authorise the Application with Your Microsoft OneDrive Account

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 you to explicitly add this app to the Microsoft MyApps portal. To add an approved app to your apps, click on the ellipsis in the top-right corner and select "Request new apps." On the next page, you can add this app. If it's not listed, you should make a request through your IT department.

This client supports the following methods to authenticate the application with Microsoft OneDrive:

• Supports interactive browser-based authentication using OAuth2 and a redirect URI
• Supports seamless Single Sign-On (SSO) via Intune using the Microsoft Identity Device Broker D-Bus interface
• Supports OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts

Interactive Authentication using OAuth2 and a redirect URI

When you run the application for the first time, the recommended authentication method is interactive browser-based OAuth2 authentication. The application will direct you to the Microsoft login page, where you sign in with your Microsoft Account and grant the application permission to access your files.

When the application detects that it is running inside a graphical desktop session, it will automatically open the Microsoft authorisation URL and listen locally for the Microsoft authorisation response. By default, the application uses the browser configured by your desktop environment. If the BROWSER environment variable is set, the application will first attempt to use the browser executable specified by that variable. In this mode, you do not need to manually copy and paste the redirect URI from your browser back into the terminal.

When no graphical desktop session is detected, or when the local browser-based authentication flow cannot be used, the application will fall back to the existing manual copy-and-paste authentication method. This fallback behaviour may also occur when running remotely via SSH, inside containers, under WSL, or when no supported browser launch mechanism is available.

Graphical Desktop Authentication using the Local Browser Redirect

When running inside a supported graphical desktop environment, the application will open the Microsoft authorisation URL and wait for the Microsoft authorisation response on:

http://127.0.0.1:53100/

By default, the application uses the browser configured by your desktop environment. To use a specific browser for interactive authentication, set the BROWSER environment variable to the browser executable when starting the client. For example, to use Microsoft Edge:

BROWSER=/usr/bin/microsoft-edge-stable onedrive --reauth

If the browser executable is available through your PATH, the executable name can be used instead:

BROWSER=microsoft-edge-stable onedrive --reauth

The same override can be used during initial authentication by running the client without --reauth:

BROWSER=microsoft-edge-stable onedrive

If the browser configured by BROWSER cannot be launched, the application falls back to the normal desktop browser launch mechanism. The BROWSER value is treated as a browser executable name or path; it is not interpreted as a shell command.

This local listener is only used during the authentication process. It binds only to the loopback interface, does not require any inbound firewall changes, and is closed once authentication has completed or failed.

Following successful graphical authentication, including an explicit --reauth, the completion page also displays an optional Help sustain OneDrive Client for Linux section with a link to support ongoing development, testing and maintenance through GitHub Sponsors. Sponsorship is entirely optional. This section is not shown as a desktop notification and is not added to normal terminal or synchronisation output.

Example Terminal Session within Graphical Desktop session:

user@hostname:~$ onedrive
D-Bus message bus daemon is available; GUI notifications are now enabled
Using IPv4 and IPv6 (if configured) for all network operations
Attempting to contact the Microsoft OneDrive Service
Successfully reached the Microsoft OneDrive Service
Configuring Global Azure AD Endpoints

Opening the Microsoft authorisation URL in your default browser ...
Waiting for the browser authorisation response on http://127.0.0.1:53100/

The application has been successfully authorised, but no extra command options have been specified.

Please use 'onedrive --help' for further assistance in regards to running this application.

user@hostname:~$

Graphical Desktop OAuth2 Authentication Process Illustrated:

The successful initial-authentication examples below include the optional project sponsorship section described above.

Fedora graphical authentication example:

Ubuntu graphical authentication example:

Important

The local authentication listener is only started for the duration of the authentication process and only listens on 127.0.0.1. No external system can connect to this listener because it only binds to the local loopback interface (127.0.0.1).

Manual Browser Authentication using Copy and Paste

If the application is not running inside a graphical desktop session, or if the graphical browser authentication process cannot be used, the application will use the manual browser authentication method.

In this mode, you will be prompted to open a specific URL in your web browser. This URL takes you to the Microsoft login page, where you sign in with your Microsoft Account and grant the application permission to access your files.

After granting permission, your browser will redirect you to a blank page, or a page that displays this message:

This is expected behaviour.

At this point, copy the full redirect URI shown in your browser's address bar and paste it into the terminal where prompted.

Example Terminal Session:

user@hostname:~$ onedrive
D-Bus message bus daemon is available; GUI notifications are now enabled
Using IPv4 and IPv6 (if configured) for all network operations
Attempting to contact Microsoft OneDrive Login Service
Successfully reached Microsoft OneDrive Login Service
Configuring Global Azure AD Endpoints

Please authorise this application by visiting the following URL:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=d50ca740-c83f-4d1b-b616-12c519384f0c&scope=Files.ReadWrite%20Files.ReadWrite.All%20Sites.ReadWrite.All%20offline_access&response_type=code&prompt=login&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

After completing the authorisation in your browser, copy the full redirect URI (from the address bar) and paste it below.

Paste redirect URI here: https://login.microsoftonline.com/common/oauth2/nativeclient?code=<redacted>

The application has been successfully authorised, but no extra command options have been specified.

Please use 'onedrive --help' for further assistance in regards to running this application.

user@hostname:~$

Manual OAuth2 Authentication Process Illustrated:

Important

Without additional input or configuration, the OneDrive Client for Linux will automatically adhere to default application settings during synchronisation processes with Microsoft OneDrive.

Important

Handling a AADSTS70000 response

If authentication fails with:

AADSTS70000: The provided value for the 'code' parameter is not valid.`

this is not a client bug.

Microsoft authorisation codes are single-use and short-lived, so the code you pasted is no longer redeemable.

Common causes when using manual browser authentication:

• Browser extensions / privacy tools modifying the redirect URL (for example, ad-blockers or 'remove tracking parameters' features within browsers)
• Copying the wrong URL (ensure you copy from the browser address bar immediately after consent)
• Refreshing the page or reusing the same redirect URI (codes can only be redeemed once)
• Waiting too long before pasting the URL back

Remediation steps for AADSTS70000:

1. Re-run: onedrive --reauth
2. Use a private/incognito browser session or a clean browser profile
3. Temporarily disable URL-filtering/privacy extensions for the Microsoft login pages (uBlock Origin / ClearURLs / Brave Shields / similar), then retry

Business / Enterprise Authentication and Admin Consent

When using Microsoft OneDrive Personal accounts, application authorisation is typically granted directly by the user during the authentication process.

In Microsoft 365 Business, Enterprise, Education, Government, or other Microsoft Entra ID managed environments, application access may be restricted by organisational security policies. In these environments, users may be unable to authorise the application themselves and may receive messages indicating that administrator approval is required.

If administrator approval is required, a Microsoft Entra ID administrator must review and grant consent for the application before users within the organisation can successfully authenticate and use the client.

The OneDrive Client for Linux uses delegated Microsoft Graph API permissions and, in most environments, does not require any modification of the application source code or the creation of a custom Microsoft Entra ID application registration.

To simplify administrator approval, a tenant-specific administrator consent URL can be generated using:

onedrive --display-admin-consent-url

This option requires the configuration value azure_tenant_id to be set in the user configuration file. The tenant identifier may be either the Microsoft Entra ID tenant GUID or the tenant domain name, for example:

azure_tenant_id = "example.onmicrosoft.com"

or

azure_tenant_id = "0c4be463-a1ab-499b-99e0-da08ce52a2cc"

The generated URL should be provided to the Microsoft Entra ID administrator responsible for approving applications within the organisation:

onedrive --display-admin-consent-url
...
Attempting to contact the Microsoft OneDrive Service
Successfully reached the Microsoft OneDrive Service
Configuring Global Azure AD Endpoints - Single Tenant Application

Please authorise this application by visiting the following Microsoft Entra ID admin consent URL: 

https://login.microsoftonline.com/0c4be463-a1ab-499b-99e0-da08ce52a2cc/v2.0/adminconsent?client_id=d50ca740-c83f-4d1b-b616-12c519384f0c&scope=Files.ReadWrite%20Files.ReadWrite.All%20Sites.ReadWrite.All%20offline_access&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

Open this URL as a Microsoft Entra ID administrator to grant tenant-wide consent. Nothing from this process needs to be pasted back into this application.

After administrator consent has been granted, run the normal authentication process again.

Important

When using the default OneDrive Client for Linux application registration, the redirect URI remains:

https://login.microsoftonline.com/common/oauth2/nativeclient

even when azure_tenant_id is configured for a single Microsoft Entra ID tenant.

This behaviour is required because the default application registration is configured with the Microsoft Identity Platform using the common native-client redirect URI.

The azure_tenant_id value is used to scope authentication and token issuance to a specific tenant, but does not change the redirect URI used by the default application registration.

Administrator consent is typically a one-time action for a Microsoft Entra ID tenant. Once consent has been granted, users can authenticate and reauthenticate normally, including when using --reauth.

If you are uncertain whether administrator approval is required in your environment, contact your Microsoft 365 or Microsoft Entra ID administrator before attempting further authentication troubleshooting.

Tip

To obtain the required 'azure_tenant_id' details, sign in to your Microsoft Entra Admin Center and review the details under Identity -> Overview

Important

Some organisations prohibit users from granting consent to applications. In these environments, authentication will fail until approval has been granted by a Microsoft Entra ID administrator.

Important

Handling an AADSTS50011 response

If authentication fails with:

AADSTS50011: The redirect URI specified in the request does not match the redirect URIs configured for the application

Microsoft Entra ID is rejecting the redirect URI supplied during authentication.

Common causes:

• Using a custom application_id where the configured redirect URI does not match the application registration
• Using an application registration that has not been configured as a Public Client Application
• Missing or incorrectly configured redirect URI entries within the Microsoft Entra ID application registration
• Using a custom Microsoft Entra ID application registration that does not include both redirect URIs required by the authentication method being used
• Application registration changes not yet replicated across Microsoft Entra ID

For users of the default OneDrive Client for Linux application registration:

The application may use one of the following redirect URIs during authentication:

• http://127.0.0.1:53100/ (browser-based authentication when a graphical desktop environment is detected)
• https://login.microsoftonline.com/common/oauth2/nativeclient (manual browser authentication fallback)

If you are using a custom Microsoft Entra ID application registration, ensure that both redirect URIs are configured correctly and that the application is configured as a Public Client Application.

If this error occurs while using the default application registration, ensure you are running the latest application release, allow time for Microsoft Entra ID application registration changes to replicate, then re-run:

onedrive --reauth

Important

When using a custom Microsoft Entra ID application registration via application_id, ensure that the following redirect URIs are configured in your application registration:

• http://127.0.0.1:53100/
• https://login.microsoftonline.com/common/oauth2/nativeclient

The first redirect URI is used for browser-based authentication within graphical desktop sessions. The second redirect URI is used for manual browser authentication and as a fallback authentication method.

Failure to configure both redirect URIs may result in authentication failures such as AADSTS50011.

Single Sign-On (SSO) via Intune using the Microsoft Identity Device Broker

To use this method of authentication, you must add the following configuration to your 'config' file:

use_intune_sso = "true"

The application checks for the required Microsoft Identity Broker D-Bus capability and can automatically activate the broker when it is registered but not already running. Broker availability does not guarantee that authentication is ready, particularly before graphical login. See Microsoft Intune SSO and systemd startup for validated user-service, SSH-login, graphical-login and lingering behaviour. When the required capability is available, the following will be displayed:

...
Client has been configured to use Intune SSO via Microsoft Identity Broker dbus session - checking usage criteria
Intune SSO via Microsoft Identity Broker dbus session usage criteria met - will attempt to authenticate via Intune
...

Important

Intune Authentication – Validated Component Versions

Component	Red Hat Enterprise Linux 9.8	Red Hat Enterprise Linux 10.2	Ubuntu 24.04	Ubuntu 26.04
Microsoft Edge	microsoft-edge-stable-155.0.4283.45-1.x86_64	microsoft-edge-stable-155.0.4283.45-1.x86_64	microsoft-edge-stable 155.0.4283.45-1	microsoft-edge-stable 155.0.4283.45-1
Microsoft Identity Broker	microsoft-identity-broker-3.0.2-1.el9.x86_64	microsoft-identity-broker-3.0.2-1.el10.x86_64	microsoft-identity-broker 3.0.2-noble	microsoft-identity-broker 3.0.2-resolute
Intune Portal	intune-portal-1.2609.5-1.el9.x86_64	intune-portal-1.2609.5-1.el10.x86_64	intune-portal 1.2609.5-noble	intune-portal 1.2609.5-resolute
dbus	dbus-1.12.20-8.el9.x86_64	dbus-1.14.10-5.el10.x86_64	dbus 1.14.10-4ubuntu4.1	dbus 1.16.2-2ubuntu4
dbus-broker	dbus-broker-28-9.el9_8.x86_64	dbus-broker-36-5.el10_2.x86_64	not separately queried	not separately queried

Microsoft Intune integration was tested and validated with onedrive v2.5.11-63-g47c9a3c using the above distributions and package versions on: 13 October 2026

On all four platforms, the client detected the Microsoft Identity Broker D-Bus session, confirmed that the Intune SSO usage criteria were met, authenticated successfully, and operated correctly against Microsoft OneDrive.

Important

The installation and configuration of Microsoft Intune for your platform is beyond the scope of this documentation.

OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts

To use this method of authentication, you must add the following configuration to your 'config' file:

use_device_auth = "true"

You will be required to open a URL using a web browser, and enter the code that this application presents:

Configuring Global Azure AD Endpoints

Authorise this application by visiting:

https://microsoft.com/devicelogin

Enter the following code when prompted: ABCDEFGHI

This code expires at: 2025-Jun-02 15:27:30

You will have ~15 minutes before the code expires.

Important

Limitation: OAuth2 Device Authorization Flow and Personal Microsoft Accounts

While the OneDrive Client for Linux fully supports OAuth2 Device Authorisation Flow (device_code grant) for Microsoft Entra ID (Work/School) accounts, Microsoft currently does not allow this flow to be used with personal Microsoft accounts (MSA) unless the application is explicitly authorised by Microsoft.

Application Configuration Summary:

• signInAudience: AzureADandPersonalMicrosoftAccount
• allowPublicClient: true
• Uses Microsoft Identity Platform v2.0 endpoints (/devicecode, /token, etc.)
• Microsoft Graph scopes properly defined

Despite this correct configuration, users signing in with a Personal Microsoft OneDrive account will see the following error:

"The code you entered has expired. Get a new code from the device you're trying to sign in to and try again."

This occurs even if the code is entered immediately. Microsoft redirects the user to:

https://login.live.com/ppsecure/post.srf?username=......

This behaviour confirms that Microsoft blocks the device_code grant flow for MSA accounts on unapproved (by Microsoft) applications.

Recommendation:
If using a Personal Microsoft OneDrive account (e.g., @outlook.com or @hotmail.com), please complete authentication using the interactive authentication method detailed above.

Further Reading:
Microsoft Documentation — OAuth 2.0 device authorisation grant

Display Your Applicable Runtime Configuration

To verify the configuration that the application will use, use the following command:

onedrive --display-config

This command will display all the relevant runtime interpretations of the options and configurations you are using. An example output is as follows:

Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
onedrive version                             = vX.Y.Z-A-bcdefghi
Config path                                  = /home/user/.config/onedrive
Config file found in config path             = true
Config option 'drive_id'                     = 
Config option 'sync_dir'                     = ~/OneDrive
...
Config option 'webhook_enabled'              = false

Important

When using multiple OneDrive accounts, it's essential to always use the --confdir command followed by the appropriate configuration directory. This ensures that the specific configuration you intend to view is correctly displayed.

Understanding OneDrive Client for Linux Operational Modes

There are two modes of operation when using the client:

1. Standalone sync mode that performs a single sync action against Microsoft OneDrive.
2. Ongoing sync mode that continuously syncs your data with Microsoft OneDrive.

Tip

To understand further the client operational modes and how the client operates, please review the client architecture documentation.

Important

The default setting for the OneDrive Client on Linux will sync all data from your Microsoft OneDrive account to your local device. To avoid this and select specific items for synchronisation, you should explore setting up 'Client Side Filtering' rules. This will help you manage and specify what exactly gets synced with your Microsoft OneDrive account.

Standalone Synchronisation Operational Mode (Standalone Mode)

This method of use can be employed by issuing the following option to the client:

onedrive --sync

For simplicity, this can be shortened to the following:

onedrive -s

Ongoing Synchronisation Operational Mode (Monitor Mode)

This method of use can be utilised by issuing the following option to the client:

onedrive --monitor

For simplicity, this can be shortened to the following:

onedrive -m

Note

This method of use is used when enabling a systemd service to run the application in the background.

In --monitor mode, the client performs recurring synchronisation cycles. A synchronisation cycle may be started because:

• the client has started or restarted and is performing its initial synchronisation pass;
• the configured monitor_interval has elapsed;
• a local filesystem event has been detected by the monitor engine;
• a Microsoft OneDrive API signal has been received via WebSocket or webhook support.

The application configuration option monitor_interval is the scheduled idle interval. It is not a guarantee that no synchronisation work can occur before that interval has elapsed.

A normal synchronisation cycle may include several different activities:

1. querying Microsoft OneDrive for online changes;
2. processing received online changes;
3. performing a database consistency and integrity check against locally stored data;
4. scanning the local filesystem for new local data to upload, when uploads are enabled;
5. performing a final online true-up to ensure the local and online state are reconciled.

These activities are not all the same thing.

The log message:

Performing a database consistency and integrity check on locally stored data

means the client is validating its local database state against the local filesystem. It does not, by itself, mean that the client is performing an online full-scan true-up.

The configuration option monitor_fullscan_frequency only controls the scheduled online full-scan true-up cadence in --monitor mode. An online full-scan true-up is when the client deliberately does not use the stored Microsoft Graph /delta link for that pass and instead performs a broader online reconciliation pass. The database consistency check and local filesystem scan may still occur during normal monitor sync cycles.

Machine-readable monitor runtime status

When --monitor is running, the client publishes a small machine-readable JSON status document in the same application state directory as the items.sqlite3 database:

monitor-status.json

For a default user configuration this is normally:

~/.config/onedrive/monitor-status.json

For an alternate configuration directory, the file is created alongside the items.sqlite3 used by that configuration. The resolved status-file location is also displayed by the application's runtime configuration output.

This capability is enabled by default through:

monitor_status = "true"

and can be disabled with:

monitor_status = "false"

The file is a runtime observability interface. It publishes state the monitor process already knows; creating or updating it does not perform an additional Microsoft Graph request, database reconciliation or filesystem scan. It is independent of display_memory and does not require verbose or debug logging.

A typical status document while a monitor cycle is running resembles:

{
    "application": "onedrive",
    "conditions": {
        "onedrive_reachability": "reachable",
        "system_time": "TIME_OK"
    },
    "instance_id": "1027995-2026-10-01T21:43:16.2285174Z",
    "mode": {
        "download_only": false,
        "monitor": true,
        "monitor_interval_seconds": 300,
        "upload_only": false
    },
    "pid": 1027995,
    "process": {
        "current_cycle_started_at": "2026-10-01T21:43:26.9855399Z",
        "last_loop_completed_at": "",
        "monitor_loop": 1,
        "runtime_seconds": 10,
        "started_at": "2026-10-01T21:43:16.2285174Z",
        "state": "syncing"
    },
    "schema_version": 1,
    "sync": {
        "initial_successful_sync_completed": false,
        "last_cycle": {
            "completed_at": "",
            "download_failures": 0,
            "duration_seconds": 0,
            "recycle_bin_failures": 0,
            "result": "never_run",
            "started_at": "",
            "upload_failures": 0
        },
        "last_successful_sync_at": "",
        "successful_cycle_count": 0
    },
    "updated_at": "2026-10-01T21:43:26.9855405Z"
}

The key fields are:

Field	Meaning
schema_version	Version of the JSON status schema. Consumers should use this when validating compatibility.
pid / instance_id	Identity of the monitor process instance that owns the status document.
mode	Relevant operating-mode values, including download_only, upload_only and the scheduled monitor interval.
process.state	Current monitor runtime state. During active reconciliation this is syncing; after a successful completed cycle this is idle; a non-successful completed cycle is represented as degraded.
process.monitor_loop	Current scheduled monitor-loop number.
process.current_cycle_started_at	UTC timestamp for the currently running scheduled monitor cycle, or an empty string when no cycle is active.
process.last_loop_completed_at	UTC timestamp for the most recently completed scheduled monitor cycle.
sync.initial_successful_sync_completed	Becomes true after this process instance completes its first successful monitor synchronisation cycle. This is particularly useful as a service-readiness signal.
sync.successful_cycle_count	Number of successfully completed monitor synchronisation cycles for the current process instance.
sync.last_successful_sync_at	UTC timestamp of the most recent successful cycle.
sync.last_cycle.result	Result of the most recently completed scheduled cycle. Values include success, partial_failure, service_unreachable, time_unsafe, interrupted and never_run.
sync.last_cycle.*_failures	Counts of failed downloads, uploads and local Recycle Bin moves recorded for the most recently completed cycle. Detailed failed paths remain in the normal application output/log rather than being duplicated into the JSON status file.
conditions.onedrive_reachability	Current known Microsoft OneDrive reachability state, such as reachable, unreachable or unknown during very early startup.
conditions.system_time	The application's canonical system-time validation state, for example TIME_OK.
updated_at	UTC timestamp when the status document was last published.

Important

monitor-status.json and --display-sync-status answer different questions.

• monitor-status.json reports the operational state and outcome of the running --monitor process.
• --display-sync-status performs a separate read-only point-in-time assessment of whether Microsoft OneDrive and the configured local filesystem scope are currently converged.

For example, a --download-only monitor can have sync.initial_successful_sync_completed = true and a most recent cycle result of success, while --display-sync-status reports NOT IN SYNC because additional local-only files exist. Both results are correct: the monitor successfully completed all work permitted by its configured operating mode, while the local and remote data states are not identical.

All status timestamps are emitted in UTC and use a trailing Z. This is deliberate so monitoring systems can compare timestamps without ambiguity across hosts, containers and daylight-saving transitions. Human-facing tools should convert the UTC timestamp into the viewer's local timezone when displaying it.

The status file is written with restrictive permissions and replaced atomically so readers see a complete old or new document rather than partially-written JSON. On an orderly --monitor shutdown the file is removed. A hard termination such as SIGKILL, a process crash or loss of power can leave the last file behind, so external tooling should not treat file existence alone as definitive liveness after an abnormal termination; use the process identity and timestamps as well.

Two common errors can occur when using monitor mode:

• Initialisation failure
• Unable to add a new inotify watch

Both of these errors are local environment issues, where the following system variables need to be increased as the current system values are potentially too low:

• Open Files Soft limit (current session)
• Open Files Hard limit (current session)
• fs.inotify.max_user_watches

To determine what the existing values are on your system, use the following commands:

open files

ulimit -Sn
ulimit -Hn

inotify watches

sysctl fs.inotify.max_user_watches

Alternatively, when running the client with increased verbosity (see below), the client will display what the current configured system maximum values are:

...
All application operations will be performed in the configured local 'sync_dir' directory: /home/alex/OneDrive
OneDrive synchronisation interval (seconds): 300
Maximum allowed open files (soft):           1024
Maximum allowed open files (hard):           262144
Maximum allowed inotify user watches:        29463
Initialising local filesystem monitoring using inotify ...
...
Local filesystem monitoring using inotify is active.

To determine what value to change to, you need to count all the files and folders in your configured 'sync_dir' location:

cd /path/to/your/sync/dir
ls -laR | wc -l

To make a change to these variables using your file and folder count, use the following process:

open files

You can increase the limits for your current shell session temporarily using:

ulimit -n <new_value>

Refer to your distribution documentation to make the change persistent across reboots and sessions.

Note

systemd overrides these values for user sessions and services. If you are making a system wide change that is persistent across reboots and sessions you will also have to modify your systemd service files in the following manner:

[Service]
LimitNOFILE=<new_value>

Post the modification of systemd service files you will need to reload and restart the services.

inotify watches

sudo sysctl fs.inotify.max_user_watches=<new_value>

Once these values are changed, you will need to restart your client so that the new values are detected and used.

To make these changes permanent on your system, refer to your OS reference documentation.

Using the OneDrive Client for Linux to synchronise your data

Client Documentation

The following documents provide detailed guidance on installing, configuring, and using the OneDrive Client for Linux:

• advanced-usage.md Instructions for advanced configurations, including multiple account setups, Docker usage, dual-boot scenarios, and syncing to mounted directories.

• application-config-options.md Comprehensive list and explanation of all configuration file and command-line options available in the client.

• application-security.md Details on security considerations and practices related to the OneDrive client.

• business-shared-items.md Instructions on syncing shared items in OneDrive for Business accounts.

• client-architecture.md Overview of the client's architecture and design principles.

• docker.md Instructions for running the OneDrive client within Docker containers.

• known-issues.md List of known issues and limitations of the OneDrive client.

• national-cloud-deployments.md Information on deploying the client in national cloud environments.

• podman.md Guide for running the OneDrive client using Podman containers.

• sharepoint-libraries.md Instructions for syncing SharePoint document libraries.

• ubuntu-package-install.md Specific instructions for installing the client on Ubuntu systems.

• webhooks.md Information on configuring and using webhooks with the OneDrive client.

Further documentation not listed above can be found here: https://github.com/abraunegg/onedrive/blob/master/docs/

Please read these additional references to assist you with installing, configuring, and using the OneDrive Client for Linux.

Increasing application logging level

When running a sync (--sync) or using monitor mode (--monitor), it may be desirable to see additional information regarding the progress and operation of the client.

The client supports four levels of logging output:

1. Normal (default)

Only essential information is shown — suitable for standard usage without additional output.

2. Verbose

Enables general status and progress information. Use:

onedrive --sync --verbose

or its short form:

onedrive -s -v

3. Debug Logging

Enables detailed internal logging useful for diagnosing issues. This is activated by specifying the --verbose flag twice:

onedrive --sync --verbose --verbose

4. HTTPS Debug Logging

Enables full debug logging including HTTPS request/response information. This is typically only needed for advanced debugging of API or network issues. Activate with:

onedrive --sync --verbose --verbose --debug-https

Important

When raising a bug report or attempting to understand unexpected behaviour, it is recommended to enable debug logging using --verbose --verbose.

Only use --debug-https if explicitly requested or required, as it may expose sensitive information in logs.

Using 'Client Side Filtering' rules to determine what should be synced with Microsoft OneDrive

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:

• check_nosync: This option allows you to create a .nosync file in local directories, to skip that directory from being included in sync operations.
• skip_dir: This option allows the user to specify directories that should not be synchronised with OneDrive. It's particularly useful for omitting large or irrelevant directories from the sync process.
• skip_dotfiles: Dotfiles, usually configuration files or scripts, can be excluded from the sync. This is useful for users who prefer to keep these files local.
• skip_file: Exclude files by filename anywhere, filename wildcard anywhere, or a specific path beginning with / relative to sync_dir.
• skip_size: Skip files greater than this specific size (in MB)
• skip_symlinks: Symlinks often point to files outside the OneDrive directory or to locations that are not relevant for cloud storage. This option prevents them 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 method offers a more granular approach to synchronisation, ensuring that only the 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.

For skip_file and skip_dir, an initial / identifies the root of sync_dir, not the Linux filesystem root. For example, with sync_dir = "~/OneDrive", a rule referencing /Documents/Reports refers to ~/OneDrive/Documents/Reports. skip_file rules containing a directory path must use this leading /; a bare filename such as notes.txt or a filename wildcard such as *.txt matches files anywhere in the sync tree. skip_dir also supports directory-name matching; whether individual directory components are matched depends on skip_dir_strict_match. Refer to application-config-options.md and skip_dir for the precise rules and examples.

Important

Client Side Filtering rules are generally processed in the following order:

1. 'check_nosync'
2. 'skip_dotfiles'
3. 'skip_symlinks'
4. 'skip_dir'
5. 'skip_file'
6. 'sync_list'
7. 'skip_size'

This can be best illustrated below:

For further details please review the client architecture documentation.

Important

After changing any Client Side Filtering rule, you must perform a full re-synchronisation by using --resync.

Why 'Server Side Filtering' is not possible with Microsoft OneDrive

It is important to understand that all filtering performed by this client (including sync_list) is client-side filtering. Microsoft OneDrive and the Microsoft Graph API do not support server-side selective sync or the ability to apply include/exclude rules when retrieving data. The client must first enumerate the remote filesystem to understand its structure and state, and only then apply filtering rules locally to determine what should be synchronised. This behaviour is expected and is a direct result of platform limitations, not a defect in the client.

For further details please read the server-side filtering limitations documentation.

Testing your configuration

You can test your configuration by utilising the --dry-run CLI option. No files will be downloaded, uploaded, or removed; however, the application will display what 'would' have occurred. For example:

onedrive --sync --verbose --dry-run
Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
Using 'user' Config Dir: /home/user/.config/onedrive
DRY-RUN Configured. Output below shows what 'would' have occurred.
DRY-RUN: Copying items.sqlite3 to items-dryrun.sqlite3 to use for dry run operations
DRY RUN: Not creating backup config file as --dry-run has been used
DRY RUN: Not updating hash files as --dry-run has been used
Checking Application Version ...
Attempting to initialise the OneDrive API ...
Configuring Global Azure AD Endpoints
The OneDrive API was initialised successfully
Opening the item database ...
Sync Engine Initialised with new Onedrive API instance
Application version:  vX.Y.Z-A-bcdefghi
Account Type:         <account-type>
Default Drive ID:     <drive-id>
Default Root ID:      <root-id>
Remaining Free Space: 1058488129 KB
All application operations will be performed in: /home/user/OneDrive
Fetching items from the OneDrive API for Drive ID: <drive-id> ..
...
Performing a database consistency and integrity check on locally stored data ... 
Processing DB entries for this Drive ID: <drive-id>
Processing ~/OneDrive
The directory has not changed
...
Scanning local filesystem '~/OneDrive' for new data to upload ...
...
Performing a final true-up scan of online data from Microsoft OneDrive
Fetching items from the OneDrive API for Drive ID: <drive-id> ..

Sync with Microsoft OneDrive is complete

Performing a sync with Microsoft OneDrive

By default, all files are downloaded in ~/OneDrive. This download location is controlled by the 'sync_dir' config option.

After authorising the application, a sync of your data can be performed by running:

onedrive --sync

This will synchronise files from your Microsoft OneDrive account to your ~/OneDrive local directory or to your specified 'sync_dir' location.

Tip

Specifying the 'source of truth' for your synchronisation with Microsoft OneDrive

By default, the OneDrive Client for Linux treats your online OneDrive data as the source of truth. This means that when determining which version of a file should be trusted as authoritative, the client prioritises the state of files stored online over local copies.

In some workflows, you may prefer to treat your local files as the primary reference instead — for example, when you regularly make changes locally and want those to take precedence during conflict resolution.

To change this behaviour, enable the local-first mode by setting the configuration option in your config file:

local_first = "true"

or by using the command-line argument at runtime:

onedrive --sync --local-first

When this option is enabled, the client will prioritise local data as the source of truth when comparing file differences and resolving synchronisation conflicts.

Performing a single directory synchronisation with Microsoft OneDrive

In some cases, it may be desirable to synchronise a single directory under ~/OneDrive without having to change your client configuration. To do this, use the following command:

onedrive --sync --single-directory '<dir_name>'

Tip

If the full path is ~/OneDrive/mydir, the command would be onedrive --sync --single-directory 'mydir'

Performing a 'one-way' download synchronisation with Microsoft OneDrive

In some cases, it may be desirable to 'download only' from Microsoft OneDrive. To do this, use the following command:

onedrive --sync --download-only

This will download all the content from Microsoft OneDrive to your ~/OneDrive location. Any files that are deleted online will remain locally and will not be removed.

Important

There is an application functionality change between v2.4.x and v.2.5x when using this option.

In prior v2.4.x releases, online deletes were automatically processed, thus automatically deleting local files that were deleted online, however there was zero way to perform a --download-only operation to archive the online state.

In v2.5.x and above, when using --download-only the default is that all files will remain locally as an archive of your online data rather than being deleted locally if deleted online.

Tip

If you have the requirement to clean up local files that have been removed online, use the following command:

onedrive --sync --download-only --cleanup-local-files

Performing a 'one-way' upload synchronisation with Microsoft OneDrive

In certain scenarios, you might need to perform an 'upload only' operation to Microsoft OneDrive. This means that you'll be uploading data to OneDrive, but not synchronising any changes or additions made elsewhere. Use this command to initiate an upload-only synchronisation:

onedrive --sync --upload-only

Important

• The 'upload only' mode operates independently of OneDrive's online content. It doesn't check or sync with what's already stored on OneDrive. It only uploads data from the local client.
• If a local file or folder that was previously synchronised with Microsoft OneDrive is now missing locally, it will be deleted from OneDrive during this operation.

Tip

If you have the requirement to ensure that all data on Microsoft OneDrive remains intact (e.g., preventing deletion of items on OneDrive if they're deleted locally), use this command instead:

onedrive --sync --upload-only --no-remote-delete

Important

• --upload-only: This command will only upload local changes to OneDrive. These changes can include additions, modifications, moves, and deletions of files and folders.
• --no-remote-delete: Adding this command prevents the deletion of any items on OneDrive, even if they're deleted locally. This creates a one-way archive on OneDrive where files are only added and never removed.

Performing a selective synchronisation via 'sync_list' file

Selective synchronisation allows you to sync only specific files and directories.

To enable selective synchronisation, create a file named sync_list in your application configuration directory (default is ~/.config/onedrive).

Important

Important points to understand before using 'sync_list'.

• 'sync_list' excludes everything by default on OneDrive.
• 'sync_list' follows an "exclude overrides include" rule, and requires explicit inclusion.
• Order specific exclusions before inclusions, so that anything specifically included is included.
• How and where you place your / matters for excludes and includes in subdirectories.

Each line of the 'sync_list' file represents a relative path from your sync_dir. All files and directories not matching any line of the file will be skipped during all operations.

Caution

Rules without slashes (Codes, Work, Backup, notes.txt, etc.) are the most expensive form of sync_list rule as this instructs the client to scan every folder online & local to find a match. As a result, these types of rules can cause:

• High CPU usage
• High disk or network activity
• Increased fan usage (especially on laptops)

If you want best performance, always prefer fully-qualified or path-scoped 'sync_list' rules. Avoid generic includes unless absolutely necessary.

Example 'sync_list' rules

# ======================================================================
# Example sync_list
# ======================================================================
# IMPORTANT:
# - 'sync_list' EXCLUDES EVERYTHING by default.
# - Exclusions come first.
# - Inclusions follow.
#
# Matching behaviour:
# - Rules WITHOUT a slash (e.g., "Backup", "notes.txt") match ANYWHERE.
#   ⚠️ These rules force exhaustive scanning of ALL online and local folders.
#   ⚠️ They are computationally expensive.
#
# - Rules with a leading "/" apply ONLY to the OneDrive ROOT.
#
# - Rules with a trailing "/" match DIRECTORIES only.
#
# Wildcards and globbing:
# - "*"   matches any characters within a single path segment.
# - "**"  matches directories RECURSIVELY across ANY depth.
# ======================================================================

# ----------------------------------------------------------------------
# EXCLUSIONS (ALWAYS PUT THESE FIRST)
# ----------------------------------------------------------------------

# Exclude temporary folders inside ANY Documents folder (any level)
!Documents/temp*

# Exclude Secret_data ONLY in OneDrive root
!/Secret_data/*

# ----------------------------------------------------------------------
# Modern development / programming exclusions
# (Common cache/build folders used by many languages & tools)
# ----------------------------------------------------------------------

# Python virtual environments
!venv/*
!.venv/*
!__pycache__/*

# Node.js / JavaScript build directories
!node_modules/*
!.next/*

# Java & Kotlin build caches
!build/kotlin/*
!.kotlin/*

# Gradle build system cache
!.gradle/*

# JetBrains IDE caches
!.idea/libraries/*
!.idea/caches/*

# Generic runtime caches
!.cache/*


# ----------------------------------------------------------------------
# INCLUSIONS (WHAT YOU *DO* WANT TO SYNC)
# ----------------------------------------------------------------------

# Include the Backup folder OR any file/folder named "Backup" ANYWHERE.
# ⚠️ High-cost rule — causes full tree scanning.
Backup

# Include Documents directory ANYWHERE
# ⚠️ High-cost rule — causes full tree scanning.
Documents/

# Include all PDF files inside any Documents folder
# ⚠️ High-cost rule — causes full tree scanning.
Documents/*.pdf

# Include one specific file, if present inside ANY Documents folder
# ⚠️ High-cost rule — causes full tree scanning.
Documents/latest_report.docx

# Include the /Backup/ folder ONLY in the OneDrive root
/Backup/

# Include Blender ONLY if in root
/Blender


# ----------------------------------------------------------------------
# PROJECT / DEVELOPMENT STRUCTURES WITH WILDCARDS & GLOBBING
# ----------------------------------------------------------------------

# Include any folder or file beginning with "Project" inside ANY Work/ folder
# ⚠️ High-cost rule — causes full tree scanning.
Work/Project*

# Include the 'Blog' directory — and ONLY that specific folder
# .
# ├── Parent
# │   ├── Blog
# │   │   ├── random_files
# │   │   │   ├── CZ9aZRM7U1j7pM21fH0MfP2gywlX7bqW
# │   │   │   └── k4GptfTBE2z2meRFqjf54tnvSXcXe30Y
# │   │   └── random_images
# │   │       ├── cAuQMfX7qsMIOmzyQYdELikZwsXeCYsL
# │   │       └── GqjZuo7UBB0qjYM2WUcZXOvToAhCQ29M
# │   └── other_stuffs
#
/Parent/Blog/*

# Include Android build directories located ANYWHERE inside ANY project
!/Programming/Projects/Android/**/build/*

# Include Android NDK /.cxx build trees ANYWHERE inside ANY project
!/Programming/Projects/Android/**/.cxx/*

# Include Web build output directories across ANY nested depth
!/Programming/Projects/Web/**/build/*

# Include the entire /Programming directory from OneDrive root
/Programming


# ----------------------------------------------------------------------
# FILE-BY-NAME MATCHING ANYWHERE
# ----------------------------------------------------------------------

# Match all files named exactly "notes.txt" ANYWHERE
# ⚠️ High-cost rule — causes full tree scanning.
notes.txt


# ----------------------------------------------------------------------
# DIRECTORIES WITH SPACES
# ----------------------------------------------------------------------
# - There is zero requirement to escape space sequences within the 'sync_list' file

# Include directories under ANY Pictures folder
# ⚠️ High-cost rule — causes full tree scanning.
Pictures/Camera Roll
Pictures/Saved Pictures

# Include 'Camera Roll' and all files / folders 
/Pictures/Camera Roll/*

# Include 'Saved Pictures' and all files / folders 
/Pictures/Saved Pictures/*


# ----------------------------------------------------------------------
# GENERIC NAME MATCHES (⚠️ VERY EXPENSIVE)
# These match ANY file or folder with that name ANYWHERE in OneDrive.
# They cause full, exhaustive scanning of ALL online and local folders.
# ----------------------------------------------------------------------

Cinema Soc
Codes
Textbooks
Year 2
Documents
Pictures
Music

The following are supported for pattern matching and exclusion rules:

• Use the * to wildcard select any characters to match for the item to be included
• Use either ! or - characters at the start of the line to exclude an otherwise included item

Important

After changing the sync_list, you must perform a full re-synchronisation by adding --resync to your existing command line - for example: onedrive --sync --resync

Tip

When enabling the use of 'sync_list,' utilise the --display-config option to validate that your configuration will be used by the application, and test your configuration by adding --dry-run to ensure the client will operate as per your requirement.

Tip

In some circumstances, it may be required to sync all the individual files within the 'sync_dir' root, but due to frequent name change / addition / deletion of these files, it is not desirable to constantly change the 'sync_list' file to include / exclude these files and force a resync. To assist with this, enable the following in your configuration file:

sync_root_files = "true"

This will tell the application to sync any file that it finds in your 'sync_dir' root by default, negating the need to constantly update your 'sync_list' file.

Using 'sync_list' with OneDrive Personal Shared Folders (Shortcuts)

When using sync_list with OneDrive Personal shared folders that have been added to your OneDrive as shortcuts, it is important to understand that these are not standard directories within your OneDrive file hierarchy.

A shared folder is represented as a shortcut (link) to content stored in another location (for example, another user's OneDrive). Because of this:

Important

Including only the parent directory that contains shared-folder shortcuts does not guarantee that the client will traverse and synchronise the contents of those shared folders.

For example, given the following structure:

SHARED_FOLDERS/
SHARED_FOLDERS/SUB_FOLDER_1/
SHARED_FOLDERS/SUB_FOLDER_1/CORE/
SHARED_FOLDERS/SUB_FOLDER_1/DEEP_SOURCE/

The following sync_list rule:

/SHARED_FOLDERS/

will include the shared-folder shortcut entries only, but will not reliably trigger traversal into the contents of those shared folders.

To ensure correct behaviour, explicitly include each shared-folder shortcut path that you want to synchronise:

/SHARED_FOLDERS/SUB_FOLDER_1/CORE/
/SHARED_FOLDERS/SUB_FOLDER_1/DEEP_SOURCE/

Note

Using wildcard rules such as /SHARED_FOLDERS/* will only include the shared-folder shortcut entries and does not guarantee traversal into the contents of those shared folders.

Tip

Treat each shared-folder shortcut as an independent root for the purposes of sync_list. Always explicitly include the exact shared-folder paths you want synchronised.

Checking synchronisation status without performing a sync

Use --display-sync-status when you need to determine whether the configured sync scope has pending work without actually performing a synchronisation:

onedrive --display-sync-status

This command exists as a safe diagnostic alternative to running --sync, --dry-run, or especially --resync simply to answer the question "is this client currently in sync?". It performs a read-only point-in-time assessment in both directions:

• Microsoft OneDrive -> Local filesystem - examines pending Microsoft Graph delta changes that would require local reconciliation, including new files and directories, remote deletions, moves or renames, file-content changes, and timestamp-only differences.
• Local filesystem -> Microsoft OneDrive - compares the local filesystem with the client's stored sync database to identify new local files and directories, modified files, timestamp-only differences, locally missing items, and other changes that normal synchronisation would need to reconcile.

The command does not upload, download, rename or delete files, does not modify the live sync database, and does not advance the stored Microsoft Graph delta cursor. This means it can be run repeatedly without consuming the pending changes it is reporting.

A clean result is reported as:

Synchronization status for the configured sync scope:

Microsoft OneDrive -> Local filesystem
  No pending remote changes detected.

Local filesystem -> Microsoft OneDrive
  No pending local changes detected.

Overall status: IN SYNC
No pending local or remote changes were detected for the configured sync scope.

When changes are pending, the relevant direction includes a summary of the work detected. Transfer quantities are estimates; for values of at least 1 KiB the client displays both a human-readable value and the exact byte count, for example:

Approximate download data:    14.15 MB (14838177 bytes)
Approximate upload data:      14.15 MB (14838177 bytes)

Small non-zero values are shown directly in bytes rather than being rounded down to 0 KB.

The final state has three possible values:

• IN SYNC - no pending local or remote changes were detected for the configured scope.
• NOT IN SYNC - at least one pending local or remote change was positively identified.
• INDETERMINATE - no pending change was positively identified, but one or more parts of the configured scope could not be assessed completely enough to assert a clean state.

INDETERMINATE is intentionally conservative. A --single-directory status request is assessed differently from a full-drive query: the client performs a read-only /children traversal of the requested online directory, compares that authoritative current-state tree with the stored database scope, and resolves tracked items missing from the tree as deleted or moved out of scope. Full-scope configurations that cannot use the normal /delta feed, a full-scope query with tracked state but no stored delta cursor, or separately traversed shared-folder sources that are not covered by the requested scope may still be incomplete; any such limitation is printed with the result.

Client-side filtering is honoured. Items excluded by skip_file, skip_dir, sync_list, skip_dotfiles, check_nosync, or applicable size limits are not treated as pending work for the configured sync scope. One-way modes are also reflected in the output: --upload-only still reports remote changes for visibility, while --download-only still reports local differences but notes that uploads are disabled.

To assess only one configured directory, combine the command with --single-directory:

onedrive --display-sync-status --single-directory 'Documents'

For this scoped form the client does not consume the default-drive delta cursor. It builds the current online directory tree directly, compares that tree with the tracked database state for the same scope, and can therefore detect new/changed items, moves within or out of the scope, and tracked items that are no longer present online.

Important

--display-sync-status reports its assessment in the textual Overall status field. A NOT IN SYNC result is not itself a command execution failure, so do not use the process exit status as a substitute for parsing the reported sync state.

The result is a point-in-time reconciliation assessment based on the current local filesystem, the client's stored sync database and the remote change feed. It is not a byte-for-byte comparison of every object stored in Microsoft OneDrive.

Performing a --resync

A --resync operation instructs the client to delete its local state database and fully rebuild it from the current online OneDrive contents. This is a powerful recovery and re-alignment action that should be used sparingly and with care.

Important

Do not use --resync as part of normal or routine operation.

A --resync is not a “refresh” or “force sync” button. It is a destructive recovery action that discards the client’s local sync history and forces a rebuild based solely on the current online OneDrive state.

Habitually using --resync has several negative impacts:

• It removes the historical sync context the client uses to safely resolve conflicts.
• It can cause unnecessary uploads, downloads, and renames.
• It increases the chance of triggering rate-limiting (HTTP 429 responses) from the Microsoft Graph API.
• It can mask underlying configuration or permission issues that should be properly diagnosed instead.

If you are unsure whether the client is in sync, do not run --resync. Instead, use:

onedrive --display-sync-status

Only use --resync when the client explicitly requests it or when a documented configuration change requires it.

When a --resync is required

You must perform a --resync after modifying any of the following configuration items:

• check_nosync
• drive_id
• sync_dir
• skip_file
• skip_dir
• skip_dotfiles
• skip_size
• skip_symlinks
• sync_business_shared_items
• Creating, modifying, or deleting the sync_list file

You may also use --resync if you believe the local state has become inconsistent with online OneDrive state. However, if you only want to check the current sync status, run:

onedrive --display-sync-status

This shows whether you are up-to-date without requiring a resynchronisation.

Exit status when a --resync is required

When the client determines that it cannot safely continue until a --resync is performed, it exits with status 78. This is the traditional EX_CONFIG value and indicates that the client has detected an application configuration or persisted-state condition that requires operator action before normal synchronisation can continue.

This status is intentionally distinct from the generic application failure status (1). It allows scripts and service managers to detect a mandatory resync condition without conflicting with shell-reserved exit statuses. The supplied systemd service files use exit status 78 in RestartPreventExitStatus, so systemd will not repeatedly restart the client when a resync is required.

To resolve the condition, re-run the client with --resync appended to the normal synchronisation mode being used, for example:

onedrive --sync --resync
onedrive --monitor --resync

Important

Versions prior to v2.5.12 used exit status 126 for this condition. Scripts, monitoring integrations, and service definitions that explicitly test for status 126 must be updated to test for status 78 instead.

What happens when you use --resync

When invoking --resync, the client displays one of the following prompts depending on the client version.

v2.5.9 and below

The usage of --resync will delete your local 'onedrive' client state, thus no record of your current 'sync status' will exist.
This has the potential to overwrite local versions of files with perhaps older versions of documents downloaded from OneDrive, resulting in local data loss.
If in doubt, backup your local data before using --resync

Are you sure you wish to proceed with --resync? [Y/N]

v2.5.10 and above

WARNING: You have asked the client to perform a --resync operation.

         This operation will delete the client’s local state database and rebuild it entirely from the current online OneDrive state.

         Because the previous sync state will no longer be available, the following may occur:
         * Local files that also exist in OneDrive may have local changes overwritten by the cloud version if a conflict cannot be safely resolved.
         * Local conflict data may be preserved as `safeBackup` files when the local bytes differ from the authoritative online version. In the specific case where an item was deleted online but changed locally, the local file may be renamed to a `safeBackup` while the online deletion is honoured.
         * The initial synchronisation pass may involve a large number of file uploads and downloads.
         * The increased activity against the Microsoft Graph API may trigger HTTP 429 (throttling) responses during the synchronisation process.

         For safest operation:
         * Ensure you have a current backup of your sync_dir.
         * Run this command first with --dry-run to confirm all planned actions.
         * Enable 'use_recycle_bin' so that online deletion events from OneDrive are moved to your system Trash rather than deleted from your local disk.

If in doubt, stop now and back up your local data before continuing.

Are you sure you wish to proceed with --resync? [Y/N]

You must press Y or y to continue with --resync action. Any other entry will exit the application.

Understanding the --resync risks and behaviour

A --resync does not delete local-only files. When a file exists locally but not in OneDrive, and is not excluded via a sync_list rule, it is treated as new local content and will be uploaded during the resynchronisation process.

Local deletion of such files when using --resync only occurs when using the explicit local data destructive modes such as:

--download-only --cleanup-local-files

The risks associated with --resync stem entirely from the loss of the local historic state:

• The client no longer knows which side previously held the authoritative version of your data.
• Conflict handling still protects local data using safeBackup preservation when the local bytes differ from the authoritative online state. A clean resync where local and online content already match does not create a safeBackup.
• Upload and download volumes may spike significantly.
• Increased calls to the Microsoft Graph API may result in temporary throttling (HTTP 429 responses).

This makes it essential that users verify actions with --dry-run and maintain proper backups.

Best-practice guidance when using --resync

1. Always back up your data. This client is not a backup system. Ensure your sync_dir is protected with real backup tooling such as:

   • rsnapshot
   • borg
   • restic
   • Timeshift
   • ZFS or Btrfs snapshots

2. Use --dry-run before a real --resync

   Allows you to preview all intended changes without modifying your filesystem.

3. Enable the Recycle Bin feature

   Set use_recycle_bin = "true" in your application configuration. When enabled:

   • Online deletions received from OneDrive via the Graph API are moved to the FreeDesktop.org-compliant system Trash rather than being permanently deleted from your disk.

4. Avoid using --resync unnecessarily

   Only use it:

   • When the client explicitly requests it, or
   • When you’ve confirmed, via logs or sync status, that the local state has become invalid

Caution

Avoid configuring --resync as a default startup option.

Automated environments

If you fully understand the implications and are operating in a scripted or automated environment, you may bypass the confirmation prompt by adding:

--resync-auth

This should only be used when automation requires non-interactive operation and robust backups are in place.

Performing a --force-sync without a --resync or changing your configuration

In some cases and situations, you may have configured the application to skip certain files and folders using 'skip_file' and 'skip_dir' configuration. You then may have a requirement to actually sync one of these items, but do not wish to modify your configuration, nor perform an entire --resync twice.

The --force-sync option allows you to sync a specific directory, ignoring your 'skip_file' and 'skip_dir' configuration and negating the requirement to perform a --resync.

To use this option, you must run the application manually in the following manner:

onedrive --sync --single-directory '<directory_to_sync>' --force-sync <add any other options needed or required>

When using --force-sync, you'll encounter the following warning and advice:

WARNING: Overriding application configuration to use application defaults for skip_dir and skip_file due to --sync --single-directory --force-sync being used

Using --force-sync will reconfigure the application to use defaults. This may have unknown future impacts.
By proceeding with this option, you accept any impacts, including potential data loss resulting from using --force-sync.

Are you sure you want to proceed with --force-sync [Y/N] 

To proceed with --force-sync, you must type 'y' or 'Y' to allow the application to continue.

Enabling the Client Activity Log

When running onedrive, all actions can be logged to a separate log file. This can be enabled by using the --enable-logging flag or by adding enable_logging = "true" to your 'config' file.

By default, log files will be written to /var/log/onedrive/ and will be in the format of %username%.onedrive.log, where %username% represents the user who ran the client to allow easy sorting of user to client activity log.

Note

You will need to ensure the existence of this directory and that your user has the applicable permissions to write to this directory; otherwise, the following error message will be printed:

ERROR: Unable to access /var/log/onedrive
ERROR: Please manually create '/var/log/onedrive' and set appropriate permissions to allow write access
ERROR: The requested client activity log will instead be located in your user's home directory

On many systems, ensuring that the log directory exists can be achieved by performing the following:

sudo mkdir /var/log/onedrive
sudo chown root:users /var/log/onedrive
sudo chmod 0775 /var/log/onedrive

Additionally, you need to ensure that your user account is part of the 'users' group:

cat /etc/group | grep users

If your user is not part of this group, then you need to add your user to this group:

sudo usermod -a -G users <your-user-name>

If you need to make a group modification, you will need to 'logout' of all sessions / SSH sessions to log in again to have the new group access applied.

If the client is unable to write the client activity log, the following error message will be printed:

ERROR: Unable to write the activity log to /var/log/onedrive/%username%.onedrive.log
ERROR: Please set appropriate permissions to allow write access to the logging directory for your user account
ERROR: The requested client activity log will instead be located in your user's home directory

If you receive this error message, you will need to diagnose why your system cannot write to the specified file location.

Client Activity Log Example:

An example of a client activity log for the command onedrive --sync --enable-logging is below:

2023-Sep-27 08:16:00.1128806    Configuring Global Azure AD Endpoints
2023-Sep-27 08:16:00.1160620    Sync Engine Initialised with new Onedrive API instance
2023-Sep-27 08:16:00.5227122    All application operations will be performed in: /home/user/OneDrive
2023-Sep-27 08:16:00.5227977    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:16:00.7780979    Processing changes and items received from Microsoft OneDrive ...
2023-Sep-27 08:16:00.7781548    Performing a database consistency and integrity check on locally stored data ... 
2023-Sep-27 08:16:00.7785889    Scanning the local file system '~/OneDrive' for new data to upload ...
2023-Sep-27 08:16:00.7813710    Performing a final true-up scan of online data from Microsoft OneDrive
2023-Sep-27 08:16:00.7814668    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:16:01.0141776    Processing changes and items received from Microsoft OneDrive ...
2023-Sep-27 08:16:01.0142454    Sync with Microsoft OneDrive is complete

An example of a client activity log for the command onedrive --sync --verbose --enable-logging is below:

2023-Sep-27 08:20:05.4600464    Checking Application Version ...
2023-Sep-27 08:20:05.5235017    Attempting to initialise the OneDrive API ...
2023-Sep-27 08:20:05.5237207    Configuring Global Azure AD Endpoints
2023-Sep-27 08:20:05.5238087    The OneDrive API was initialised successfully
2023-Sep-27 08:20:05.5238536    Opening the item database ...
2023-Sep-27 08:20:05.5270612    Sync Engine Initialised with new Onedrive API instance
2023-Sep-27 08:20:05.9226535    Application version:  vX.Y.Z-A-bcdefghi
2023-Sep-27 08:20:05.9227079    Account Type:         <account-type>
2023-Sep-27 08:20:05.9227360    Default Drive ID:     <redacted>
2023-Sep-27 08:20:05.9227550    Default Root ID:      <redacted>
2023-Sep-27 08:20:05.9227862    Remaining Free Space: <space-available>
2023-Sep-27 08:20:05.9228296    All application operations will be performed in: /home/user/OneDrive
2023-Sep-27 08:20:05.9228989    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:20:06.2076569    Performing a database consistency and integrity check on locally stored data ... 
2023-Sep-27 08:20:06.2077121    Processing DB entries for this Drive ID: <redacted>
2023-Sep-27 08:20:06.2078408    Processing ~/OneDrive
2023-Sep-27 08:20:06.2078739    The directory has not changed
2023-Sep-27 08:20:06.2079783    Processing Attachments
2023-Sep-27 08:20:06.2080071    The directory has not changed
2023-Sep-27 08:20:06.2081585    Processing Attachments/file.docx
2023-Sep-27 08:20:06.2082079    The file has not changed
2023-Sep-27 08:20:06.2082760    Processing Documents
2023-Sep-27 08:20:06.2083225    The directory has not changed
2023-Sep-27 08:20:06.2084284    Processing Documents/file.log
2023-Sep-27 08:20:06.2084886    The file has not changed
2023-Sep-27 08:20:06.2085150    Scanning the local file system '~/OneDrive' for new data to upload ...
2023-Sep-27 08:20:06.2087133    Skipping item - excluded by sync_list config: ./random_25k_files
2023-Sep-27 08:20:06.2116235    Performing a final true-up scan of online data from Microsoft OneDrive
2023-Sep-27 08:20:06.2117190    Fetching items from the OneDrive API for Drive ID: <redacted>
2023-Sep-27 08:20:06.5049743    Sync with Microsoft OneDrive is complete

Client Activity Log Differences

Despite application logging being enabled as early as possible, the following log entries will be missing from the client activity log when compared to console output:

No user configuration file:

No user or system config file found, using application defaults
Using 'user' configuration path for application state data: /home/user/.config/onedrive
Using the following path to store the runtime application log: /var/log/onedrive

User configuration file:

Reading configuration file: /home/user/.config/onedrive/config
Configuration file successfully loaded
Using 'user' configuration path for application state data: /home/user/.config/onedrive
Using the following path to store the runtime application log: /var/log/onedrive

Display Manager Integration

Modern desktop environments such as GNOME and KDE Plasma provide graphical file managers — Nautilus (GNOME Files) and Dolphin, respectively — to help users navigate their local and remote storage.

What “Display Manager Integration” means

Display Manager Integration refers to an ability to integrate your configured Microsoft OneDrive synchronisation directory (sync_dir) with the desktop’s file manager environment. Depending on the platform and desktop environment, this may include:

1. Sidebar registration — Adding the OneDrive folder as a “special place” within the sidebar of Nautilus (GNOME) or Dolphin (KDE), providing easy access without manual navigation.
2. Custom folder icon — Applying a dedicated OneDrive icon to visually distinguish the synchronised directory within the file manager.
3. Context-menu extensions — Adding right-click actions such as “Upload to OneDrive” or “Share via OneDrive” directly inside Nautilus or Dolphin.
4. File overlay badges — Displaying icons (check-marks, sync arrows, or cloud symbols) to represent file synchronisation state.
5. System tray or application indicator — Presenting sync status, pause/resume controls, or notifications via a tray icon.

What display manager integration is available in the OneDrive Client for Linux

The OneDrive Client for Linux currently supports the following integration features:

1. Sidebar registration — The client automatically registers the OneDrive folder as a “special place” within the sidebar of Nautilus (GNOME) or Dolphin (KDE).
2. Custom folder icon — The client applies a OneDrive-specific icon to the synchronisation directory where supported by the installed icon theme.

Sidebar registration and custom folder icon behaviour is controlled by the configuration option:

display_manager_integration = "true"

When enabled, the client detects the active desktop session and applies the corresponding integration automatically when the client is running in --monitor mode only.

Note

Display Manager Integration remains active only while the OneDrive client or its systemd service is running. If the client stops or the service is stopped, the desktop integration is automatically cleared. It is re-applied the next time the client starts.

Fedora (GNOME) Display Manager Integration Example

Fedora (KDE) Display Manager Integration Example

Ubuntu Display Manager Integration Example

Kubuntu Display Manager Integration Example

Additionally, the following display manager integrations are independent from the above configuration specification:

1. GUI Notifications — The client (when compiled with --enable-notifications) will send notifications to the GUI when important events occur.
2. Recycle Bin — When use_recycle_bin = "true" is enabled, the client uses the FreeDesktop.org Trash Specification–compliant recycle bin for any online deletions that are processed locally. This capability can be utilised even when no GUI is available.

What about context menu integration?

Context-menu integration is a desktop-specific capability, not part of the core OneDrive Client. It can be achieved through desktop-provided extension mechanisms:

1. Shell-script bridge — A simple shell script can be registered as a KDE ServiceMenu or a GNOME Nautilus Script to trigger local actions (for example, creating a symbolic link in ~/OneDrive to upload a file).
2. Python + Nautilus API (GNOME) — Implemented via nautilus-python bindings by registering a subclass of Nautilus.MenuProvider.
3. Qt/KIO Plugins (KDE) — Implemented using C++ or declarative .desktop ServiceMenu definitions under /usr/share/kservices5/ServiceMenus/.

These methods are optional and operate independently of the core OneDrive Client. They can be used by advanced users or system integrators to provide additional right-click functionality.

What about file overlay badges?

File overlay badges are typically associated with Microsoft’s Files-On-Demand feature, which allows selective file downloads and visual state indicators (online-only, available offline, etc.).

Because Files-On-Demand is currently a feature request for this client, overlay badges are not implemented and remain out of scope for now.

What about a system tray or application indicator?

While the core OneDrive Client for Linux does not include its own tray icon or GUI dashboard, the community provides complementary tools that plug into it — exposing sync status, pause/resume controls, tray menus, and GUI configuration front-ends. Below are two popular options:

1. OneDriveGUI - https://github.com/bpozdena/OneDriveGUI

• A full-featured graphical user interface built for the OneDrive Linux client.
• Key features include: multi-account support, asynchronous real-time monitoring of multiple OneDrive profiles, a setup wizard for profile creation/import, automatic sync on GUI startup, and GUI-based login.
• Includes tray icon support when the desktop environment allows it.
• Intended to simplify one-click configuration of the CLI client, help users visualise current operations (uploads/downloads), and manage advanced features such as SharePoint libraries and multiple profiles.

2. onedrive_tray - https://github.com/DanielBorgesOliveira/onedrive_tray

• A lightweight system tray utility written in Qt (using libqt5 or later) that monitors the running OneDrive Linux client and displays status via a tray icon.
• Left-click the tray icon to view sync progress; right-click to access a menu of available actions; middle-click shows the PID of the running client.
• Ideal for users who just want visual status cues (e.g., “sync in progress”, “idle”, “error”) without a full GUI configuration tool.

GUI Notifications

To enable GUI notifications, you must compile the application with GUI Notification Support. Refer to GUI Notification Support for details. Once compiled, GUI notifications will work by default in the display manager session under the following conditions:

• A D-Bus message bus daemon must be running.
• The environment variables XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS must be set.

Without these conditions met, GUI notifications will not function even if the support is compiled in.

Once these conditions have been met, the following application events will trigger a GUI notification within the display manager session by default:

• Aborting a sync if .nosync file is found
• Skipping a particular item due to an invalid name
• Skipping a particular item due to an invalid symbolic link
• Skipping a particular item due to an invalid UTF sequence
• Skipping a particular item due to an invalid character encoding sequence
• Cannot create remote directory
• Cannot upload file changes (free space issue, breaches maximum allowed size, breaches maximum OneDrive Account path length)
• Cannot delete remote file / folder
• Cannot move remote file / folder
• When a re-authentication is required
• When a new client version is available
• Files that fail to upload
• Files that fail to download

Additionally, GUI notifications can also be sent for the following activities:

• Successful file download
• Successful file upload
• Successful deletion locally (files and folders)
• Successful deletion online (files and folders)

To enable these specific notifications, add the following to your 'config' file:

notify_file_actions = "true"

When running in --monitor mode, the client sends a concise GUI notification when monitor mode becomes active. The notification summarises the local and remote monitoring mechanisms applicable to the current configuration, for example:

Monitor mode active — inotify enabled, WebSocket enabled

To disable only this monitor-start notification while retaining the detailed console startup status and all other GUI notifications, add the following to your 'config' file:

notify_monitor_start = "false"

To disable all GUI notifications, add the following to your 'config' file:

disable_notifications = "true"

Using a local Recycle Bin

By default, this application will process online deletions and directly delete the corresponding file or folder directly from your configured 'sync_dir'.

In some cases, it may actually be desirable to move these files to your Linux user default 'Recycle Bin', so that you can manually delete the files at your own discretion.

To enable this application functionality, add the following to your 'config' file:

use_recycle_bin = "true"

This capability is designed to be compatible with the FreeDesktop.org Trash Specification, ensuring interoperability with GUI-based desktop environments such as GNOME (GIO) and KDE (KIO). It follows the required structure by:

• Moving deleted files and directories to ~/.local/share/Trash/files/
• Creating matching metadata files in ~/.local/share/Trash/info/ with the correct .trashinfo format, including the original absolute path and ISO 8601-formatted deletion timestamp
• Resolving filename collisions using a name.N.ext pattern (e.g., Document.2.docx), consistent with GNOME and KDE behaviour.

To specify an explicit 'Recycle Bin' directory, add the following to your 'config' file:

recycle_bin_path = "/path/to/desired/location/"

The same FreeDesktop.org Trash Specification will be used with this explicit 'Recycle Bin' directory as illustrated below:

Important

The use_recycle_bin option only applies when a deletion originates from Microsoft OneDrive online, or from another OneDrive client, and this client then needs to remove the corresponding local file or folder.

It does not protect files or folders that you delete locally from your configured sync_dir.

If you delete files locally from sync_dir, this client treats that as an intentional local delete and will propagate that delete to Microsoft OneDrive during synchronisation. By the time this client detects the local delete, the data has already been removed from the local filesystem, so the client cannot move it to the local Recycle Bin.

If you want locally deleted files to go to Trash first, you must delete them using your desktop environment’s Trash mechanism, such as GNOME Files, KDE Dolphin, or another tool that implements the FreeDesktop.org Trash Specification. Do not use rm, shred, scripts, terminal cleanup commands, or manually delete the sync directory while the client or systemd service is still running unless you intend those deletes to be synchronised online.

Handling a Microsoft OneDrive Account Password Change

If you change your Microsoft OneDrive Account Password, the client will no longer be authorised to sync, and will generate the following error upon next application run:

AADSTS50173: The provided grant has expired due to it being revoked, a fresh auth token is needed. The user might have changed or reset their password. The grant was issued on '<date-and-timestamp>' and the TokensValidFrom date (before which tokens are not valid) for this user is '<date-and-timestamp>'.

ERROR: You will need to issue a --reauth and re-authorise this client to obtain a fresh auth token.

To re-authorise the client, follow the steps below:

1. If running the client as a system service (init.d or systemd), stop the applicable system service
2. Run the command onedrive --reauth. This will clean up the previous authorisation, and will prompt you to re-authorise the client as per initial configuration. Please note, if you are using --confdir as part of your application runtime configuration, you must include this when telling the client to re-authenticate.
3. Restart the client if running as a system service or perform the standalone sync operation again

The application will now sync with OneDrive with the new credentials.

Determining the synchronisation result

When the client has finished syncing without errors, the following will be displayed:

Sync with Microsoft OneDrive is complete

If any items failed to sync, the following will be displayed:

Sync with Microsoft OneDrive has completed, however there are items that failed to sync.

A file list of failed upload or download items will also be listed to allow you to determine your next steps.

When running in --monitor mode with monitor_status = "true", the same cycle outcome is also reflected in monitor-status.json. A clean cycle is recorded as sync.last_cycle.result = "success"; cycles containing failed transfers are recorded as partial_failure together with the applicable failure counts. See Machine-readable monitor runtime status.

In order to fix the upload or download failures, you may need to:

• Review the application output to determine what happened
• Re-try your command utilising a resync to ensure your system is correctly synced with your Microsoft OneDrive Account

Resumable Transfers

The OneDrive Client for Linux supports resumable transfers for both uploads and downloads. This capability enhances the reliability and robustness of file transfers by allowing interrupted operations to continue from the last successful point, instead of restarting from the beginning. This is especially important in environments with unstable network connections or during large file transfers.

What Are Resumable Transfers?

A resumable transfer is a process that:

• Detects when a file upload or download was interrupted due to a network error, system shutdown, or other external factors.
• Saves the current state of the transfer, including offsets, temporary filenames, and online session metadata.
• Upon application restart, automatically detects these incomplete operations and resumes them from where they left off.

When Does It Occur?

Resumable transfers are automatically engaged when:

• The application is not started with --resync.
• Interrupted downloads exist with associated metadata saved to disk.
• Interrupted uploads using session-based transfers are pending resumption.

Important

If a --resync operation is being performed, all resumable transfer metadata is purged to ensure a clean and consistent resynchronisation state.

How It Works Internally

• Downloads: Partial download state is stored as a JSON metadata file, including the online hash, download URL, and byte offset. The file itself is saved with a .partial suffix. When detected, this metadata is parsed and the download resumes using HTTP range headers.
• Uploads: Session uploads use OneDrive Upload Sessions. If interrupted, the session URL and transfer state are persisted. On restart, the client attempts to resume the upload using the remaining byte ranges.

Benefits of Resumable Transfers

• Saves bandwidth by avoiding full re-transfer of large files.
• Improves reliability in poor network conditions.
• Increases performance and reduces recovery time after unexpected shutdowns.

Considerations

Resumable state is only preserved if the client exits gracefully or the system preserves temporary files across sessions.

If --resync is used, all resumable data is discarded intentionally.

Recommendations

• Avoid using --resync unless explicitly required.
• Enable logging (--enable-logging) to help diagnose resumable transfer behaviour.
• For environments where network interruptions are common, ensure that the system does not clean temporary or cache files between reboots.

Note

Resumable transfer support is built-in and requires no special configuration. It is automatically applied during both standalone and monitor operational modes when applicable.

Frequently Asked Configuration Questions

How to change the default configuration of the client?

The OneDrive Client for Linux determines its configuration from three layers, applied in the following order of priority:

1. Application default values – internal defaults built into the client
2. Configuration file values – user-defined settings from a config file (if present)
3. Command-line arguments – values passed at runtime override both of the above

The built-in application defaults are sufficient for most users and provide a reliable operational baseline. Adding a configuration file or command-line options is optional, and only required when you want to customise application 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 config file if you wish to override those defaults.

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

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

Tip

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

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

For a full list of configuration options and command-line switches, see application-config-options.md

How to change where my data from Microsoft OneDrive is stored?

By default, the location where your Microsoft OneDrive data is stored, is within your Home Directory under a directory called 'OneDrive'. This replicates as close as possible where the Microsoft Windows OneDrive client stores data.

To change this location, the application configuration option 'sync_dir' is used to specify a new local directory where your Microsoft OneDrive data should be stored.

Important

Using a network mount point such as NFS, CIFS, SMB, Windows Network Share or Samba Network Share as your sync_dir has significant change-detection and performance implications.

These network-backed filesystems should be treated as not providing usable inotify support for this client. inotify support is essential for Monitor Mode to detect local filesystem changes in real time. When sync_dir is located on a network mount, local file changes may not generate inotify events at all, meaning the client cannot immediately detect those changes as they occur.

In this configuration, synchronisation between the local filesystem and Microsoft OneDrive will rely on scheduled monitor sync cycles controlled by monitor_interval, rather than immediate local filesystem event detection.

Additionally, local filesystem notifications on network mounts do not behave the same way as they do on local disks. Changes made directly on the NAS, file server, or from another client may not be reported to this client. On very large sync trees this can be expensive, because the local database consistency check and local filesystem scan must validate state across the mounted filesystem.

This limitation is caused by network filesystem and operating system notification behaviour, and is outside the control of this client.

For large datasets, local storage is strongly preferred. If a network-backed sync_dir is required, test Monitor Mode behaviour and scan duration carefully before relying on it for unattended operation.

How do I safely remove my local sync_dir without deleting my OneDrive data?

Caution

Do not delete your configured sync_dir while the client is running.

A local delete inside sync_dir is treated as an intentional synchronisation action. The client may detect this through inotify events in monitor mode, or during a filesystem scan, and then propagate the delete to Microsoft OneDrive.

To remove the local copy without deleting online data:

1. Stop all running onedrive processes.
2. Stop any configured systemd service, for example:

systemctl --user stop onedrive

3. Confirm no client process is still running:

pgrep -a onedrive

4. Move the local sync directory out of the way first:

mv ~/OneDrive ~/OneDrive.local-backup

5. Only delete the backup after you are certain the client is stopped and you no longer need the local data.

If you accidentally deleted local files while the client was still running, immediately stop the client and check the Microsoft OneDrive online Recycle Bin.

Why does the client create 'safeBackup' files?

safeBackup files are a local data-preservation mechanism used when the client has evidence that locally stored file content would otherwise be displaced while reconciling with Microsoft OneDrive.

A safeBackup is not created merely because a synchronisation or --resync is being performed, and it is not created simply because file timestamps or other metadata differ. The decision is based on whether the local file contains data that is different from both the authoritative online version and, where available, the last locally recorded in-sync database state.

From v2.5.3+, the backup name is:

filename-hostname-safeBackup-0001.ext

The client increments the four-digit number when another preservation file is required. If an existing same-device safeBackup already preserves the same file content and metadata, the client may reuse that preservation rather than creating another numbered duplicate.

How replacement-style safeBackup preservation works

For normal replacement and conflict-resolution workflows, the client does not rename the canonical file away before the replacement is ready. The existing canonical pathname remains present while the replacement is downloaded to a .partial staging file and validated. If the current local bytes must be preserved, the client first creates the required safeBackup preservation entry without removing the canonical pathname. Where appropriate, this can use a filesystem hard link to retain the existing local file object efficiently, with an independent verified copy used where required or where hard-link creation is unavailable. The validated replacement is then committed to the original canonical pathname.

The expected successful state is therefore:

original filename                  -> authoritative replacement
filename-hostname-safeBackup-0001 -> preserved previous local content

If the replacement download, validation, safeBackup creation, or final promotion fails, the existing canonical file is retained. A required safeBackup failure is treated as a hard preservation failure and the client refuses to replace the canonical file.

There is one intentional exception: when a file has been deleted online but independently modified locally, there is no online replacement to place back under the original name. In this specific workflow the modified local file is renamed to a safeBackup and the online deletion is honoured.

When a safeBackup is created

The client can create a safeBackup in the following situations:

1. A tracked file changed both locally and online

The local file differs from the last in-sync database version and the authoritative online file also differs. Before applying the online replacement, the client preserves the local version as a safeBackup.

If the local file still matches the last in-sync database version, it has not been independently modified locally and no safeBackup is required before applying the online update. Likewise, if the local bytes already match the incoming online bytes, no safeBackup is required.

2. A same-path local file exists without a usable database identity and differs from OneDrive

This can occur after --resync, after loss/removal of the local state database, or when a synchronisation directory is shared with another OneDrive client or operating system. Because there is no trustworthy previous local database baseline, the client compares the local file content with the online file. If the hashes differ, the local file is preserved before the authoritative online version is applied.

Importantly, --resync itself does not create a safeBackup. If the local file is already in sync and its content hash matches OneDrive, the client rebuilds its database/metadata state without creating a safeBackup and without replacing identical file content. When rebuilding synchronisation state, file timestamp equality alone is not treated as proof that file content is identical; where content identity must be established, the file content hash is also compared.

3. A remote move or rename targets a locally occupied destination

If an online move or rename must place a file at a local pathname that is already occupied by different unsynchronised local content, the destination content is preserved as a safeBackup before the remote move is committed locally.

A destination that is already tracked and confirmed in sync does not require preservation merely because it occupies the target pathname.

4. A locally modified tracked file conflicts with a newer online file during upload processing

If the client is preparing to upload a modified tracked file but discovers that the online file is newer, the local version is preserved as a safeBackup and the preservation copy can be uploaded under its safeBackup filename. In normal bidirectional operation the newer online canonical file can then be applied locally. In --upload-only mode the client does not force that download and keeps the local canonical file present.

5. A new or untracked local file collides with a newer different online file

If a local file is being treated as new but a different same-name file already exists online and the online version is newer, the local content is preserved as a safeBackup rather than overwriting the newer online object.

6. The canonical file changes while a replacement transaction is already in progress

The client rechecks the canonical file immediately before replacement. If new local content appears or the canonical bytes change while a validated replacement is being prepared, that new local state must be preserved before the replacement can be committed.

7. A file was deleted online but changed locally since the last in-sync state

The online deletion is authoritative, but the independently modified local bytes must not be discarded. This is the one preservation workflow where the original canonical pathname is intentionally removed: the modified local file is renamed to a safeBackup, and the online deletion is then honoured.

When a safeBackup should not be created

A safeBackup should not be created simply because:

• the client is running --resync
• the local and online file content is already identical
• only the local modification time or other metadata differs while file content is identical
• the online file changed but the local file still matches the last known in-sync database content
• a download fails before any replacement can be committed
• a required preservation operation itself fails

In the content-identical cases above there is no unique local file content that needs to be preserved. Where a download or required preservation operation fails, the client instead refuses to commit the replacement and retains the existing canonical file.

Can I turn this functionality off?

Yes, but be careful. To disable local data protection entirely, set the following configuration option:

bypass_data_preservation = "true"

If you enable this, the client will not create safeBackup files when conflict preservation would normally be required and may overwrite or remove local content during reconciliation. Use with extreme caution.

If you simply do not want safeBackup files uploaded to OneDrive, it is advisable to keep protection enabled and add a skip_file rule:

skip_file = "~*|.~*|*.tmp|*.swp|*.partial|*-safeBackup-*"

This keeps the preservation files local so that you can review or remove them independently without disabling data protection.

How to change what file and directory permissions are assigned to data that is downloaded from Microsoft OneDrive?

The following are the application default permissions for any new directory or file that is created locally when downloaded from Microsoft OneDrive:

• Directories: 700 - This provides the following permissions: drwx------
• Files: 600 - This provides the following permissions: -rw-------

These default permissions align to the security principal of 'least privilege' so that only you should have access to your data that you download from Microsoft OneDrive.

To alter these default permissions, you can adjust the values of two configuration options as follows. You can also use the Unix Permissions Calculator to help you determine the necessary new permissions.

sync_dir_permissions = "700"
sync_file_permissions = "600"

Important

Please note that special permission bits such as setuid, setgid, and the sticky bit are not supported. Valid permission values range from 000 to 777 only.

Note

To prevent the application from modifying file or directory permissions and instead rely on the existing file system permission inheritance, add disable_permission_set = "true" to your configuration file.

How are uploads and downloads managed?

The system manages downloads and uploads using a multi-threaded approach. Specifically, the application utilises by default 8 threads (a maximum of 16 can be configured) for these processes. Refer to configuration documentation for further details.

How to only sync a specific directory?

There are two methods to achieve this:

• Employ the '--single-directory' option to only sync this specific path
• Employ 'sync_list' as part of your 'config' file to configure what files and directories to sync, and what should be excluded

How to 'skip' files from syncing?

There are two methods to achieve this:

• Employ 'skip_file' as part of your 'config' file to configure what files to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded

skip_file = "report.txt" excludes that filename anywhere beneath sync_dir; skip_file = "*.txt" excludes matching filenames anywhere. To exclude a specific file in a specific directory, include the leading sync-root /, for example skip_file = "/Documents/Reports/report.txt". With sync_dir = "~/OneDrive", this targets ~/OneDrive/Documents/Reports/report.txt, not an absolute Linux path. Filenames containing [, ], {, }, ^ or $ are matched literally.

For further details please read the 'skip_file' config option documentation

How to 'skip' directories from syncing?

There are three methods available to 'skip' a directory from the sync process:

• Employ 'skip_dir' as part of your 'config' file to configure what directories to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded
• Employ 'check_nosync' as part of your 'config' file and a '.nosync' empty file within the directory to exclude to skip that directory

Important

Entries for skip_dir are relative to sync_dir, not the Linux filesystem root. For example, /Documents/Cache refers to ~/OneDrive/Documents/Cache when sync_dir = "~/OneDrive". A directory-name rule such as Cache matches matching directory components anywhere when skip_dir_strict_match = "false"; strict matching disables component-by-component matching. See the detailed option documentation for explicit path and wildcard examples.

For further details please read the 'skip_dir' config option documentation

How to 'skip' .files and .folders from syncing?

There are three methods to achieve this:

• Employ 'skip_file' or 'skip_dir' to configure what files or folders to skip
• Employ 'sync_list' to configure what files and directories to sync, and what should be excluded
• Employ 'skip_dotfiles' as part of your 'config' file to skip any dot file (for example: .Trash-1000 or .xdg-volume-info) from syncing to OneDrive

How to 'skip' files larger than a certain size from syncing?

Use skip_size = "value" as part of your 'config' file where files larger than this size (in MB) will be skipped.

How to 'rate limit' the application to control bandwidth consumed for upload & download operations?

To optimise Internet bandwidth usage during upload and download processes, include the 'rate_limit' setting in your configuration file. This setting controls the bandwidth allocated to each thread.

By default, 'rate_limit' is set to '0', indicating that the application will utilise the maximum available bandwidth across all threads.

To check the current 'rate_limit' value, use the --display-config command.

Note

Since downloads and uploads are processed through multiple threads, the 'rate_limit' value applies to each thread separately. For instance, setting 'rate_limit' to 1048576 (1MB) means that during data transfers, the total bandwidth consumption might reach around 16MB, not just the 1MB configured due to the number of threads being used.

How can I prevent my local disk from filling up?

By default, the application will reserve 50MB of disk space to prevent your filesystem from running out of disk space.

This default value can be modified by adding the 'space_reservation' configuration option and the applicable value as part of your 'config' file.

You can review the value being used when using --display-config.

How does the client handle symbolic links?

Microsoft OneDrive has no concept or understanding of symbolic links, and attempting to upload a symbolic link to Microsoft OneDrive generates a platform API error. All data (files and folders) that are uploaded to OneDrive must be whole files or actual directories.

As such, there are only two methods to support symbolic links with this client:

1. Follow the Linux symbolic link and upload whatever the local symbolic link is pointing to to Microsoft OneDrive. This is the default behaviour.
2. Skip symbolic links by configuring the application to do so. When skipping, no data, no link, no reference is uploaded to OneDrive.

Use 'skip_symlinks' as part of your 'config' file to configure the skipping of all symbolic links while syncing.

How to synchronise OneDrive Personal Shared Folders?

Folders shared with you can be synchronised by adding them to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the folder you want to synchronise, and then click on "Add to my OneDrive".

How to synchronise OneDrive Business Shared Items (Files and Folders)?

Folders shared with you can be synchronised by adding them to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the folder you want to synchronise, and then click on "Add to my OneDrive".

Files shared with you can be synchronised using two methods:

1. Add a shortcut link to the file to your OneDrive folder online
2. Sync the actual file locally using the configuration option to sync OneDrive Business Shared Files.

Refer to business-shared-items.md for further details.

How to synchronise SharePoint / Office 365 Shared Libraries?

There are two methods to achieve this:

• SharePoint library can be directly added to your OneDrive online. To do that, open your OneDrive account online, go to the Shared files list, right-click on the SharePoint Library you want to synchronise, and then click on "Add to my OneDrive".
• Configure a separate application instance to only synchronise that specific SharePoint Library. Refer to sharepoint-libraries.md for configuration assistance.

How to Create a Shareable Link?

In certain situations, you might want to generate a shareable file link and provide this link to other users for accessing a specific file.

To accomplish this, employ the following command:

onedrive --create-share-link <path/to/file>

Important

By default, this access permissions for the file link will be read-only.

To make the shareable link a read-write link, execute the following command:

onedrive --create-share-link <path/to/file> --with-editing-perms

Important

The order of the file path and option flag is crucial.

How to Synchronise Both Personal and Business Accounts at once?

You need to set up separate instances of the application configuration for each account.

Refer to advanced-usage.md for guidance on configuration.

How to Synchronise Multiple SharePoint Libraries simultaneously?

For each SharePoint Library, configure a separate instance of the application configuration.

Refer to advanced-usage.md for configuration instructions.

How to Receive Real-time Changes from Microsoft OneDrive Service, instead of waiting for the next sync period?

When running in --monitor mode, the client can receive Microsoft OneDrive API change signals using either its built-in WebSocket support or the optional webhook capability. These signals allow an online change to trigger a synchronisation cycle as soon as possible, rather than relying only on the next scheduled monitor_interval.

WebSocket support is the default near real-time notification mechanism. Where the installed curl/libcurl version provides the required WebSocket capability, the client will automatically attempt to establish a WebSocket subscription to Microsoft Graph. No public listener, reverse proxy, or additional webhook configuration is required.

If WebSocket support is unsuitable for your environment, it can be disabled by setting:

disable_websocket_support = "true"

Webhooks provide an alternative notification mechanism and require explicit configuration, including a public URL that Microsoft can reach. When webhooks are enabled, WebSocket support is not used because only one Microsoft Graph API notification mechanism is active for a client instance at a time. Refer to webhooks.md for webhook configuration instructions.

Note

WebSocket and webhook notifications are change signals; they do not contain the complete synchronisation data. When a signal is received, the client queries Microsoft OneDrive through the Microsoft Graph API and performs the normal reconciliation process. The configured monitor_interval remains the scheduled fallback so that synchronisation does not depend solely on receipt of a near real-time notification.

How to initiate the client as a background service?

OneDrive can run in the background through systemd, init.d or runit. The following systemd guidance applies to distributions that provide a systemd user manager and the corresponding OneDrive unit files, including current Ubuntu, Fedora and Red Hat Enterprise Linux releases.

Choosing a systemd service

The client provides two different systemd units. Select one service type for each OneDrive configuration and synchronisation directory.

Environment	Recommended service	How it runs
Graphical desktop, desktop notifications or Microsoft Intune SSO	User service: onedrive.service	Managed by the user's systemd manager; may start at graphical or SSH login, or at boot with lingering
Headless server using previously configured, non-Intune authentication	System service: onedrive@<username>.service	Managed by the system manager; runs under the specified non-root Linux account independently of login
Headless environment requiring a persistent systemd user service	User service with lingering, where appropriate	Starts the user manager at boot; does not create a graphical desktop session

The system service does not automatically inherit a user's graphical-session environment or user D-Bus context. It is therefore not recommended for Microsoft Intune SSO or GUI notifications. For Intune SSO, use the user service and see Microsoft Intune SSO and systemd startup.

Important

Never run a system-level and user-level OneDrive service simultaneously against the same configuration, item database or synchronisation directory. Stop and disable the existing service before switching. Normal service operation should use a non-root account; running OneDrive as root can create root-owned synchronised files.

Note

The user unit must be installed in the distribution's systemd user unit directory (typically /usr/lib/systemd/user/), while the template system unit belongs in the systemd system unit directory (typically /usr/lib/systemd/system/). Check availability with systemctl --user cat onedrive.service or systemctl cat onedrive@.service respectively. The correct installation paths are determined by the distribution's systemd configuration; source installations may use /usr/local/bin/onedrive for the executable.

Running OneDrive as a non-root user with a systemd system service

This option suits headless or unattended systems using an already-authorised OneDrive configuration without a requirement for Microsoft Intune SSO or desktop notifications.

1. Sign in as the intended non-root Linux account, complete the initial authorisation and verify that a standalone synchronisation works:

   onedrive --sync --verbose
   

2. Enable and start the system service, substituting that account's username:

   sudo systemctl enable --now "onedrive@$(whoami).service"
   

3. Examine its state and logs:

   systemctl status "onedrive@$(whoami).service"
   journalctl -u "onedrive@$(whoami).service" -f
   

The system service uses the selected account but starts independently of that user's interactive login. It does not require loginctl enable-linger.

Running OneDrive with a systemd user service

Recommended for normal graphical desktop use, including desktop notifications and Microsoft Intune SSO. This procedure also works on current RHEL distributions when the systemd user unit is installed correctly; systemctl --user is not exclusive to Ubuntu, Fedora or other desktop-focused distributions.

1. Log into the graphical desktop as the user who will run OneDrive. Complete initial authorisation and verify that synchronisation works.

2. Stop and disable any existing system-level onedrive@<username>.service instance using the same configuration:

   sudo systemctl disable --now "onedrive@$(whoami).service"
   

3. Enable and start the user service as that user, without sudo:

   systemctl --user enable --now onedrive.service
   

4. Check its status and logs:

   systemctl --user status onedrive.service
   journalctl --user -u onedrive.service -f
   

Without lingering, the user service starts when the systemd user manager starts, which may happen following an SSH login as well as graphical login. This does not imply that a graphical desktop or Microsoft Identity Broker authentication is already available. The user manager normally stops after the user's last login session ends unless lingering is enabled.

Tip

Troubleshooting systemctl --user and missing XDG/D-Bus environment variables

On some Linux installations, including some SSH, su or custom login environments, systemctl --user can report:

Failed to connect to bus: No such file or directory

An absent or incorrect XDG_RUNTIME_DIR or DBUS_SESSION_BUS_ADDRESS may be responsible when the user's systemd manager and D-Bus socket are already running. Check these before changing anything:

id -u
printf 'XDG_RUNTIME_DIR=%s\n' "$XDG_RUNTIME_DIR"
printf 'DBUS_SESSION_BUS_ADDRESS=%s\n' "$DBUS_SESSION_BUS_ADDRESS"
ls -l "/run/user/$(id -u)/bus"

If the socket exists for the current user, but the environment variables are absent or incorrect, the original workaround can be applied to the current shell:

export XDG_RUNTIME_DIR="/run/user/$(id -u)"
export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"
systemctl --user status onedrive.service

If this resolves the issue, review how the login session initialises its environment (including pam_systemd, where applicable). On a system where this is an established, environment-specific requirement, the exports may be added to the relevant interactive shell startup file, such as ~/.bashrc, but not as a blanket recommendation. Re-login to test persistent changes. Do not use these variables to connect as root to another user's D-Bus socket.

Important: these exports do not create a missing user manager or D-Bus socket, and do not provide a graphical desktop session or make Microsoft Identity Broker authentication available before GUI login. If /run/user/$(id -u)/bus does not exist, investigate user-manager and PAM login-session startup instead of merely exporting the variables.

Note

Legacy Raspberry Pi and other minimal installations: Historical troubleshooting reports described systems where a root-owned user service or its XDG environment did not survive reboot reliably. Where a genuine boot-time, non-interactive service is required, the system-level onedrive@<username>.service described above is an alternative because it is managed by the system manager rather than a root user-manager session. An older workaround copied or linked configuration from /home/root/.config/onedrive to /root/.config/onedrive; do not assume that /home/root exists or that such a link is needed. Use the correct configuration for the account that will run OneDrive, and prefer a normal non-root account to avoid root-owned synchronised files.

Microsoft Intune SSO and systemd startup

When use_intune_sso = "true", OneDrive communicates with Microsoft Identity Broker over the user D-Bus. The broker can be registered as com.microsoft.identity.broker1 and marked (activatable) even when no broker process is running. The client can request automatic broker activation; D-Bus activation or ownership alone does not establish authentication readiness.

On Ubuntu 24.04, Ubuntu 26.04, RHEL 9.8 and RHEL 10.2, the following startup and recovery behaviour was validated with the updated client in October 2026:

Startup condition	Observed Intune SSO behaviour
Graphical desktop available; broker already running	Authentication succeeded
Graphical desktop available; broker inactive but D-Bus activatable	Client activated the broker and authentication succeeded
SSH login before graphical login, without lingering	Enabled user service could start, but broker authentication failed until graphical login
Boot before graphical login, with lingering enabled	User service started at boot, but broker authentication failed until graphical login
Subsequent graphical login, with or without lingering	Existing systemd restart behaviour retried OneDrive; authentication succeeded and synchronisation completed without manual restart

The supplied user unit uses Restart=on-failure and RestartSec=3, with a 15-second ExecStartPre delay. Authentication failures can therefore generate repeated failed attempts and restarts until the graphical environment is ready. This is observed recovery behaviour, not a guarantee of endless retries: systemd start limits, a different unit configuration and RestartPreventExitStatus=78 can alter restarting.

Recommended configuration: for desktop users authenticating through Microsoft Intune SSO, use systemctl --user enable --now onedrive.service and ordinarily leave lingering disabled. Enabling lingering does not make Intune SSO work before graphical login; it allows the user manager and OneDrive to start earlier. A system service should not be presented as a substitute for a functioning graphical-session broker.

Note

These observations describe the four tested operating-system environments and their installed Microsoft Identity Broker configurations. They do not establish a universal requirement for every Linux distribution or broker version. Whether token renewal continues after graphical logout was not validated by the startup/recovery tests.

OneDrive service running as root user via init.d

chkconfig onedrive on
service onedrive start

To view the logs, execute:

tail -f /var/log/onedrive/<username>.onedrive.log

To alter the 'user' under which the client operates (typically root by default), manually modify the init.d service file and adjust daemon --user root onedrive_service.sh to match the correct user.

OneDrive service running as a non-root user via runit (antiX, Devuan, Artix, Void)

1. Create the following folder if it doesn't already exist: /etc/sv/runsvdir-<username>

• where <username> is the USER targeted for the service
• e.g., # mkdir /etc/sv/runsvdir-nolan

2. Create a file called run under the previously created folder with executable permissions

   • # touch /etc/sv/runsvdir-<username>/run
   • # chmod 0755 /etc/sv/runsvdir-<username>/run

3. Edit the run file with the following contents (permissions needed):

#!/bin/sh
export USER="<username>"
export HOME="/home/<username>"

groups="$(id -Gn "${USER}" | tr ' ' ':')"
svdir="${HOME}/service"

exec chpst -u "${USER}:${groups}" runsvdir "${svdir}"

• Ensure you replace <username> with the USER set in step #1.

4. Enable the previously created folder as a service

• # ln -fs /etc/sv/runsvdir-<username> /var/service/

5. Create a subfolder in the USER's HOME directory to store the services (or symlinks)

   • $ mkdir ~/service

6. Create a subfolder specifically for OneDrive

• $ mkdir ~/service/onedrive/

7. Create a file called run under the previously created folder with executable permissions

   • $ touch ~/service/onedrive/run
   • $ chmod 0755 ~/service/onedrive/run

8. Append the following contents to the run file

#!/usr/bin/env sh
exec /usr/bin/onedrive --monitor

• In some scenarios, the path to the onedrive binary may vary. You can obtain it by running $ command -v onedrive.

9. Reboot to apply the changes

10. Check the status of user-defined services

• $ sv status ~/service/*

Note

For additional details, you can refer to Void's documentation on Per-User Services

Running the systemd user service without login (lingering)

By default, a systemd user manager starts when the user logs in, including through SSH, and normally stops after the last login session ends. Lingering changes that lifecycle: it allows the user's manager, and enabled user services, to start at boot and remain available after logout.

To enable lingering for a user:

sudo loginctl enable-linger "$(whoami)"
loginctl show-user "$(whoami)" -p Linger

To restore normal login-managed behaviour:

sudo loginctl disable-linger "$(whoami)"

Important

Lingering does not create a graphical session and does not make Microsoft Identity Broker authentication or desktop notifications available before graphical login. In the four tested Intune SSO environments, OneDrive repeatedly failed authentication before graphical login and recovered automatically after graphical login through the supplied user unit's restart policy. For Intune SSO desktop use, lingering is generally unnecessary.

How to access Microsoft OneDrive service through a proxy

If you have a requirement to run the client through a proxy, there are a couple of ways to achieve this:

Option 1: Use '.bashrc' to specify the proxy server details

Set proxy configuration in ~/.bashrc to allow the 'onedrive' application to use a specific proxy server:

# Set the HTTP proxy
export http_proxy="http://your.proxy.server:port"

# Set the HTTPS proxy
export https_proxy="http://your.proxy.server:port"

Once you've edited your ~/.bashrc file, run the following command to apply the changes:

source ~/.bashrc

Option 2: Update the 'systemd' service file to include the proxy server details

If running as a systemd service, edit the applicable systemd service file to include the proxy configuration information:

[Unit]
Description=OneDrive Client for Linux
Documentation=https://github.com/abraunegg/onedrive
After=network-online.target
Wants=network-online.target

[Service]
........
Environment="HTTP_PROXY=http://your.proxy.server:port"
Environment="HTTPS_PROXY=http://your.proxy.server:port"
ExecStart=/usr/local/bin/onedrive --monitor
........

Note

After modifying the service files, you will need to run sudo systemctl daemon-reload to ensure the service file changes are picked up. A restart of the OneDrive service will also be required to pick up the change to send the traffic via the proxy server

How to set up SELinux for a sync folder outside of the home folder

If SELinux is enforced and the sync folder is outside of the home folder, as long as there is no policy for cloud file service providers, label the file system folder to user_home_t.

sudo semanage fcontext -a -t user_home_t /path/to/onedriveSyncFolder
sudo restorecon -R -v /path/to/onedriveSyncFolder

To remove this change from SELinux and restore the default behaviour:

sudo semanage fcontext -d /path/to/onedriveSyncFolder
sudo restorecon -R -v /path/to/onedriveSyncFolder

Why do I see Performing a database consistency and integrity check on locally stored data every monitor cycle?

This message refers to the local database/filesystem consistency pass. It is not the same as an online full-scan true-up.

monitor_fullscan_frequency controls how often the client performs an online full-scan true-up in --monitor mode. It does not disable the local database consistency check and does not disable the local filesystem scan used to identify local changes that may need to be uploaded.

To confirm whether an online full-scan true-up is occurring, run the client with debug logging:

onedrive --monitor --verbose --verbose

Relevant debug messages include:

Full Scan Frequency Loop Number: ...
Perform a Full Scan True-Up: true|false
Performing a full scan of online data to ensure consistent local state
Using database stored deltaLink
Using cached deltaLink

If Perform a Full Scan True-Up is false, the client should use the cached or database-stored /delta link where applicable. Seeing the local database consistency message in the same sync cycle does not mean monitor_fullscan_frequency has been ignored.

Advanced Configuration of the OneDrive Client for Linux

Refer to advanced-usage.md for further details on the following topics:

• Configuring the client to use multiple OneDrive accounts / configurations
• Configuring the client to use multiple OneDrive accounts / configurations using Docker
• Configuring the client for use in dual-boot (Windows / Linux) situations
• Configuring the client for use when 'sync_dir' is a mounted directory
• Upload data from the local ~/OneDrive folder to a specific location on OneDrive

Overview of all OneDrive Client for Linux CLI Options

Below is a comprehensive list of all available configuration options for the OneDrive Client for Linux, as shown by the output of onedrive --help. These commands provide a range of options for synchronising, monitoring, and managing files between your local system and Microsoft's OneDrive cloud service.

The following configuration options are available:

onedrive - A client for the Microsoft OneDrive Cloud Service

  Usage:
    onedrive [options] --sync
      Do a one-time synchronisation with Microsoft OneDrive
    onedrive [options] --monitor
      Monitor filesystem and synchronise regularly with Microsoft OneDrive
    onedrive [options] --display-config
      Display the currently used configuration
    onedrive [options] --display-sync-status
      Perform a read-only bidirectional assessment of local and Microsoft OneDrive sync state
    onedrive -h | --help
      Show this help screen
    onedrive --version
      Show version

  Options:

  --auth-files '<path or required value>'
      Perform authentication via files rather than an interactive dialogue. The application reads/writes the required values from/to the specified files
  --auth-response '<path or required value>'
      Perform authentication via a supplied response URL rather than an interactive dialogue
  --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 '<path or required value>'
      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 '<path or required value>'
      Set the directory used to store the configuration files
  --create-directory '<path or required value>'
      Create a directory on OneDrive. No synchronisation will be performed
  --create-share-link '<path or required value>'
      Create a shareable link for an existing file on OneDrive
  --debug-https
      Debug OneDrive HTTPS communication.
  --destination-directory '<path or required value>'
      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-time-check
      Disable validation of the local system clock against Microsoft service time
  --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-config
      Display what options the client will use as currently configured. No synchronisation will be performed
  --display-quota
      Display the quota status of the client. No synchronisation will be performed
  --display-running-config
      Display what options the client has been configured to use on application startup
  --display-sync-status
      Display the sync status of the client. No synchronisation will be performed
  --download-file '<path or required value>'
      Download a single file from Microsoft OneDrive
  --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
      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 '<path or required value>'
      Display the file link of a synced file
  --get-sharepoint-drive-id '<path or required value>'
      Query and return the Office 365 Drive ID for a given Office 365 SharePoint Shared Library
  --help -h
      This help information.
  --list-shared-items
      List OneDrive Business Shared Items
  --local-first
      Synchronise from the local directory source first, before downloading changes from OneDrive
  --log-dir '<path or required value>'
      Directory where logging output is saved to, needs to end with a slash
  --logout
      Log out the current user
  --mirror-local-state
      Mirror the local state to Microsoft OneDrive online
  --modified-by '<path or required value>'
      Display the last modified by details of a given path
  --monitor -m
      Keep monitoring for local and remote changes
  --monitor-fullscan-frequency '<path or required value>'
      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 '<path or required value>'
      Number of seconds by which each sync operation is undertaken when idle under monitor mode
  --monitor-log-frequency '<path or required value>'
      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 '<path or required value>'
      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 '<path or required value>'
      Require a password to access the shared link when used with --create-share-link <file>
  --single-directory '<path or required value>'
      Specify a single local directory within the OneDrive root to sync
  --skip-dir '<path or required value>'
      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 '<path or required value>'
      Skip any files that match this pattern from syncing
  --skip-size '<path or required value>'
      Skip new files larger than this size (in MB)
  --skip-symlinks
      Skip syncing of symlinks
  --source-directory '<path or required value>'
      Source directory to rename or move on OneDrive. No synchronisation will be performed
  --space-reservation '<path or required value>'
      The amount of disk space to reserve (in MB) to avoid 100% disk space utilisation
  --sync -s
      Perform a synchronisation with Microsoft OneDrive
  --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 '<path or required value>'
      Specify the local directory used for synchronisation to OneDrive
  --threads
      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>

Refer to application-config-options.md for in-depth details on all application options.