OneDrive Sync Finally Has a Command-Line Tool. It’s Called odcli.

For most of OneDrive’s life, the sanctioned way to find out whether sync was working was to ask the user to hover over a cloud in the system tray and describe the colour to you. Green, good. Blue spinning, wait. Red, open a ticket. Grey, reboot and pray. This was the diagnostic protocol for a product that holds the primary working copy of a knowledge worker’s files. We all just accepted it.

That’s the backdrop for Roadmap ID 578910, which introduces odcli, an official command-line tool for the OneDrive sync app. It is not glamorous. It is years overdue. And it is the single most useful thing to happen to OneDrive operations in years, precisely because it is boring plumbing rather than a feature anyone will demo on stage.

Let me walk the chain of events that got us here, because the gaps in that chain tell you more about what to expect than the roadmap blurb does.

The long stretch where there was nothing

The modern sync client, the one that, in my experience, replaced a Groove-era mess most admins would rather forget, shipped without any supported scripting surface at all. No CLI, no module, no documented API for “is this machine in sync and if not, why not.” If you managed thousands of endpoints, your options were telemetry you didn’t fully control, event logs that lied by omission, and the colour of the cloud.

What this meant in practice: every sync incident started with a human looking at a screen. You could not answer “how many of my 4,000 laptops have sync paused right now” without deploying something custom. The data existed on each machine. You just couldn’t get at it in a way a script could read.

The community built the tool Microsoft wouldn’t

Into that vacuum, in practice, teams reached for community tooling. I watched admins deploy an unofficial PowerShell wrapper, the kind that poked at the sync client’s internals to return a status string, because there was nothing supported that did the job. In the tenants I worked with, that pattern was common enough that it was effectively the de facto standard. It worked, mostly, until a client update changed something underneath it and it quietly stopped returning accurate results, usually discovered weeks later when someone noticed the dashboard had gone suspiciously green.

That’s the tax you pay for building on an unsupported surface: it breaks on Microsoft’s schedule, not yours, and you own the fallout. The fact that an entire ecosystem of admins ended up depending on reverse-engineered tooling for years is the clearest possible signal that Microsoft had left a hole. odcli is them finally admitting it.

Roadmap 578910: the first official CLI arrives

The roadmap entry describes odcli as a command-line tool for managing and diagnosing the OneDrive sync app. Reading between the lines of what a sync-client CLI logically needs to do, the capability set lands in four buckets:

• Sync status, the thing everyone actually wants. Is this machine in sync, paused, erroring, or quota-blocked, expressed as data a script can branch on rather than a colour a human has to interpret.
• Account management, querying which accounts are signed in on the client and their state.
• Configuration queries, reading how the client is configured on this machine.
• Policy, surfacing which policies are applied and whether the client is honouring them.

The genuinely important bit, and the reason to care: JSON output. Status you can parse is status you can act on without a human in the loop. Pipe it into your RMM, your SIEM, a scheduled health check, a Power Automate flow, or, since every product note in 2026 is contractually obligated to mention it, an “AI agent.” Strip the buzzword and the real claim is modest and correct: machine-readable output means anything that reads JSON can consume OneDrive sync state. That’s it. That’s the whole unlock, and it’s enough.

Who it’s for, per the roadmap: end users, IT admins, and support engineers. The user-facing angle is a footnote. The reason this matters is that support engineers stop asking for screenshots and admins stop depending on a community DLL.

What the roadmap conspicuously does not tell you

Here’s where I stop paraphrasing the blurb and start managing your expectations.

The roadmap item does not publish the command syntax. It does not document the subcommands, the flags, or the JSON schema. So anyone handing you a ready-to-run odcli sync-status --json one-liner this week is guessing, and you should not build production monitoring on a guess, that’s exactly how the last generation of unofficial status tooling got burned. Wait for the documented schema before you parse fields by name. JSON shapes change during rollout, and a dashboard that silently mis-reads a renamed field is worse than no dashboard.

Where it installs is unconfirmed in the roadmap text. The sane assumption, do not treat it as fact until docs land, is that it ships alongside the sync client binary rather than as a separate download, which means your version management problem is the one you already have: whatever ring your OneDrive client update policy puts machines in. If you defer client updates, you defer odcli too.

And check the roadmap status yourself before you plan around it. “On the roadmap” and “on every machine in your tenant” are different calendars, sometimes by quarters. Rolling-out features arrive unevenly; a script that assumes odcli exists will throw on the half of your fleet that hasn’t received it yet.

Which is the one pattern worth writing down today, because it’s true regardless of the final syntax: test for the tool before you call it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# Illustrative wrapper. Subcommand/flag names below are PLACEHOLDERS -
# replace with the official syntax once Microsoft documents it.
# Do NOT ship this parsing untested; the JSON schema is not yet public.
​
function Get-ODCliStatus {
    [CmdletBinding()]
    param()
​
    # 1. Confirm the tool is even present on this machine (rollout is uneven)
    $cli = Get-Command 'odcli' -ErrorAction SilentlyContinue
    if (-not $cli) {
        Write-Warning "odcli not found on $env:COMPUTERNAME - client may predate the rollout."
        return [pscustomobject]@{ Computer = $env:COMPUTERNAME; Available = $false }
    }
​
    try {
        # Capture stdout; assume a JSON switch exists (verify against docs)
        $raw = & odcli status --json 2>$null   # <-- PLACEHOLDER syntax
​
        if ([string]::IsNullOrWhiteSpace($raw)) {
            throw "odcli returned no output (exit code $LASTEXITCODE)."
        }
​
        $data = $raw | ConvertFrom-Json -ErrorAction Stop
​
        [pscustomobject]@{
            Computer  = $env:COMPUTERNAME
            Available = $true
            Raw       = $data   # bind to named fields only AFTER the schema is published
        }
    }
    catch {
        Write-Error "Failed to read odcli status on $env:COMPUTERNAME: $_"
        [pscustomobject]@{ Computer = $env:COMPUTERNAME; Available = $true; Error = "$_" }
    }
}
​
# Run read-only first. Anything that CHANGES client state (resetting sync,
# signing an account out) should be gated behind explicit review and -WhatIf
# style confirmation - never fire it across a fleet straight from a query.
Get-ODCliStatus | Format-List

Note what that code does and doesn’t do. It reads. It checks for existence. It catches failure instead of assuming success. It explicitly refuses to bind JSON fields by name until the schema is real. And it flags the dangerous direction, anything that resets sync or signs an account out is state-changing, and you run that against a reviewed list with confirmation, not as a bulk action off a live inventory query. The same discipline you’d apply to a destructive Graph call applies here, even though odcli is a local binary and not Graph.

Where this sits next to what you already run

To be clear about scope: odcli does not replace the OneDrive admin center, and it does not replace the sync-health and app-management settings you configure centrally. Policy is still authored where it always was, the OneDrive admin center and Intune. odcli is the client-side half: it reports, from the endpoint, what’s actually happening and whether the policy you pushed is being honoured. Central config declares intent; the CLI tells you reality on the device. You want both, and until now you only had one.

The next beat on the calendar

The thing to watch is the roadmap status flipping to generally available, and, more importantly, the documentation that should land with it: the subcommand reference and, critically, the JSON schema. That schema is the contract. The day it’s published and stable is the day you can safely build monitoring that reads fields by name instead of eyeballing output. Until then, treat odcli as a very promising preview and parse defensively.

A decade of hovering over a tray icon is ending. Don’t celebrate by hard-coding a field name Microsoft hasn’t committed to yet.