ncstatus — quickly see what your Nextcloud sync is really doing (macOS, virtual files)

📱 Desktop & mobile clients 💻 Desktop
1

Hi all,

I’ve put together a small command-line tool for macOS and made it public in case it’s useful to anyone else.

GitHub - weiaoli2/ncstatus: See what your Nextcloud sync is actually doing on macOS - read-only diagnostics for the File Provider backend. Finds files that exist only on your Mac. · GitHub — Python 3, MIT, no dependencies.

What it’s for: if your sync ever misbehaves, this points at the problem immediately instead of leaving you guessing. It tells you which files never made it to the server, which uploads macOS has stopped retrying, what the actual error was, and what’s still queued.

That last one matters more than it sounds — a failed upload can end up marked “give up” by the system, with nothing in the UI to say so. The folder still looks complete, but the file exists only on your Mac.

It’s fast. The whole report takes about two seconds, because it asks Apple’s File Provider daemon — the thing that actually runs the sync — rather than scanning your files.

It only reads. It never opens a file (opening a placeholder would download it) and never writes anything: no config, no cache, no state.

$ ncstatus

Nextcloud   /Users/you/Library/CloudStorage/Nextcloud-cloud.example.com-you
████████████░░░░░░░░░░░░  61.2% 2.68 GB / 4.38 GB

 NOT ON SERVER   3 files   1.42 GB   these exist ONLY on this Mac
     1.31 GB    2  Projects/RenderAssets/Interiors
      112 MB    1  Documents/Scans
  why: create-item → cannot synchronize (the server refused the operation)
  2 of them have been GIVEN UP on (no further retries), last tried 21h25m ago

There’s also an optional SwiftBar menu-bar icon that turns red when files are stranded, and lets you click straight through to them in the Finder.

One important limitation: this is for the File Provider / virtual files client — the modern setup where your files live under ~/Library/CloudStorage/. If you use the older sync method, an ordinary folder elsewhere on disk, there’s nothing for it to read.

I’ve also opened a feature request suggesting the client show this itself: nextcloud/desktop#10563. A :+1: there is more useful than a reply here if you’ve run into it.

Feedback and bug reports welcome — it’s new, and so far it’s only been tested against my own setup.

1 Like