Zephyr Support

Contact

Write to zephyr@timothymorgan.info. It is the right address for everything: a file that won’t sync, a question about what Zephyr does with your data, a crash, a feature you wish existed, or a report that something in this page is wrong.

Four things make an answer much faster, if you have them to hand:

• Which Zephyr, and which version. Choose Zephyr ▸ About Zephyr from the menu bar. Say whether you installed it from the Mac App Store or downloaded it directly — the two editions differ in a few places.
• Which macOS. Apple menu ▸ About This Mac.
• What you did, and what happened instead. The exact wording of any message Zephyr showed you helps more than a description of it.
• A diagnostic report, if the problem is with syncing. See Collect a diagnostic report below — read it before you send it.

What usually goes wrong

Your Dropbox doesn’t appear in the sidebar

An account can be linked, indexed, and syncing normally and still have no row in the sidebar, because whether an app may show files there is macOS’s decision rather than Zephyr’s. Check these in order.

1. Switch Zephyr on. Apple menu ▸ System Settings ▸ General ▸ Login Items & Extensions ▸ File Providers, then turn on Zephyr. This is much the most common cause. If Zephyr isn’t listed there at all, no account is linked yet — link one first, and the switch appears.
2. Let the sidebar show cloud locations. In Finder, choose Finder ▸ Settings ▸ Sidebar, and under Locations select Cloud Storage. This one setting hides every sync app’s location at once, Zephyr’s included, and belongs to Finder rather than to Zephyr — so Zephyr can neither read it nor warn you that it is what’s wrong.
3. Install Zephyr rather than running it from the disk image. A downloaded app carries a flag that makes macOS run it out of a temporary copy, and macOS will not register a file provider for one — so Zephyr never reaches the File Providers list. Dragging the app elsewhere doesn’t clear the flag; installing it does. Quit Zephyr, then run the .pkg installer from the latest release. (App Store copies are never affected by this.)

If you’d rather leave the Cloud Storage setting alone, open your Dropbox in Finder and drag the folder’s icon from the top of the window into the sidebar’s Favorites section. A favorite doesn’t depend on that setting.

A red warning sits on one of your accounts

That means the trouble is with the account itself rather than with any one file, and nothing in it syncs while it stands. Hover the warning to read the whole reason.

• If there’s a Link Again… button, Dropbox has stopped accepting Zephyr’s authorization — you revoked it, changed your password, or Dropbox expired it. Click Zephyr in the menu bar, click Manage Accounts…, click Link Again… beside the warning, and approve access as you did the first time. Nothing is re-downloaded and no exclusion is forgotten.
• If there isn’t one, relinking isn’t the fix. A warning that Zephyr isn’t hearing from Dropbox clears itself once Dropbox answers again; a row reading “Account settings unreadable” is fixed by linking the account again from the same Manage Accounts… window.

Zephyr says it can’t reach Dropbox

This message appears once at the top of the menu-bar panel, and it is about this Mac’s connection rather than any account. Nothing is wrong with your files, and changes you make now are sent as soon as Dropbox answers. Check that the Mac is online, that syncing isn’t paused, and — if nothing else on the Mac is having trouble — Dropbox’s own status page. Zephyr keeps trying throughout and clears the message by itself. There is nothing to press.

A file won’t sync

Zephyr keeps the item and the reason rather than retrying in silence. Click Zephyr in the menu bar, then click the “couldn’t sync” row under the account: each row names the item by its path in your Dropbox and says what went wrong. Show reveals it in Finder; Dismiss takes the row off the list without changing anything.

The usual causes are an item larger than the room left in your Dropbox, a name Dropbox won’t accept, or a symbolic link, which Dropbox will not take at all. An item that can’t be shared until the account’s email is verified is waiting on you — verify the address with Dropbox and it clears. A file changed in two places at once is not a failure and won’t appear here: Dropbox keeps both copies and names the second one itself.

You don’t see Zephyr’s notifications

Notifications are granted by you in System Settings ▸ Notifications, not by Zephyr. Silenced notifications don’t affect syncing at all — files still move; you just aren’t told about it. Zephyr shows a row along the bottom of its window when macOS is withholding something it needs, with a button that opens the right pane.

The zephyr command-line tool isn’t there

The App Store edition ships without it. Installing a tool onto your PATH isn’t permitted for App Store apps, so the command-line tool comes only with the direct download, or from Homebrew with brew install --cask riscfuture/tap/zephyr. The tool also keeps its credentials separately from the app: run zephyr auth link once for the tool, even if the app is already set up.

Collect a diagnostic report

When the fix isn’t obvious, a diagnostic report is what turns “it doesn’t work” into something that can be looked into.

1. Click Zephyr in the menu bar, then click Settings…
2. Scroll to Troubleshooting, then click Collect… beside Diagnostics.
3. Finder opens with the report selected. Attach it to your email.

The report carries Zephyr’s version and yours of macOS, your settings, each linked account and its counts, and every item that couldn’t sync or that you’ve taken out of syncing — each by its full Dropbox path. It contains no file contents and no credentials, but it does name your files: read it before sending it, and remove anything you’d rather not share.

Questions

What does Zephyr require?

macOS 26 or later, and a Dropbox account. Both editions are free, and the source is public under the MIT license.

Is this made by Dropbox?

No. Zephyr is an independent, open-source client built against Dropbox’s public HTTP API, and is not affiliated with, endorsed by, or sponsored by Dropbox, Inc.

Where are my files, and what does Zephyr send anywhere?

In your Dropbox — and in macOS’s storage for them once something opens them. Zephyr keeps no mirrored folder and runs no server of its own: your files and credentials travel between your Mac and Dropbox and nowhere else. The privacy policy lists every field of every request, including the crash reports that go to Sentry.

How do I unlink an account?

Click Zephyr in the menu bar, click Manage Accounts…, then Control-click the account and choose Unlink…, then confirm. That revokes Zephyr’s access and removes it from Finder. Nothing in your Dropbox is deleted.

Do I have to leave Zephyr running?

To hear about changes made on your other devices promptly, yes — the app hosts the watcher, so remote edits show up within seconds only while Zephyr is alive. That’s what the login item offered during setup is for.

Can I use Zephyr alongside the official Dropbox client?

Zephyr reads and writes the same com.dropbox.ignored extended attribute the official client uses, so an item excluded in one is excluded in the other. Pointing both at the same account at the same time, though, isn’t something Zephyr has been designed around.

How do I report a bug or ask for a feature?

Email zephyr@timothymorgan.info, or open an issue on GitHub if you have an account there. Both reach the same person.