Synology Swap

Ever walked all the way down a long folder path in Synology Drive, only to realise the file is too heavy to open on-demand and you need it straight from the server over SMB? Then you get to redo that whole path by hand in the other place. Synology Swap does it in one click: it swaps the Synology Drive path for the matching SMB server path — and back. Works like a charm both ways. And if the server isn't mounted, it mounts it for you first.

The same shared folder is reachable two ways, with completely different paths:

• SMB — the server in Finder, /Volumes/ShareName (opens instantly)
• Synology Drive — sync-on-demand, ~/Library/CloudStorage/SynologyDrive-Name

Same file, two paths. Hopping between them by hand is the annoying part. Synology Swap adds one Finder action that takes the selected item, figures out which source you're in, and reveals its counterpart in the other one.

Features

• Both directions, auto-detected — SMB → Drive and Drive → SMB from the same button.
• Auto-mount — counterpart is on the server but the share isn't mounted? It mounts it from your Keychain and waits. If it still doesn't catch, it tells you to mount it once by hand.
• Tabs, not window spam — the counterpart opens as a Finder tab. Swap back and it returns to the existing tab instead of piling up new windows.
• Plain-text config — link folders by name, no code.
• No dependencies — pure /bin/bash (the macOS built-in) + a Finder Quick Action.

How to use it?

1. Right-click → Synology Swap 2. The counterpart opens as a second tab 3. Optional one-key shortcut

Install

With the wizard (recommended)

git clone https://github.com/Sheppfilm/synology-swap.git
cd synology-swap
./install.sh

The wizard walks through each Synology Drive folder and asks which SMB share it maps to. It never guesses an unmounted share. For each folder you can:

• confirm the mounted share it found (it matches even across name differences, e.g. Projs 2026 ⇄ Projs2026),
• mount the server right there and pick the share from the list,
• type the share name or a full path,
• or skip it and fill it in later.

Then it offers Finder tabs and installs the Quick Action. To redo just the folder mapping later, run ./install.sh --remap.

Manually

# 1. put the script somewhere on disk
mkdir -p ~/.local/bin
cp synology-swap.sh ~/.local/bin/
chmod +x ~/.local/bin/synology-swap.sh

# 2. create your config
mkdir -p ~/.config/synology-swap
cp config.example.txt ~/.config/synology-swap/config.txt
open -e ~/.config/synology-swap/config.txt   # edit the folder pairs

# 3. (optional) open counterparts as tabs instead of new windows
defaults write -g AppleWindowTabbingMode -string always

For the right-click menu entry, run ./install.sh once — it generates the Finder Quick Action for you (that part is fiddly to do by hand).

Usage

Right-click a file or folder → Services (or Quick Actions) → Synology Swap.

Faster, without the menu — assign a keyboard shortcut: System Settings → Keyboard → Keyboard Shortcuts → Services → Synology Swap. Select an item, hit the shortcut (e.g. ⌃⌥S), done.

Editing the mapping by hand

File: ~/.config/synology-swap/config.txt

@host = YOUR-SERVER.local

Company Name     | CompanyName
Projs 2026  | Projs2026
Photos_2026         | Photos-2026

One pair per line: <SMB share name> | <Synology Drive folder name>. You only type the names — the script builds the full paths (/Volumes/<SMB> and ~/Library/CloudStorage/SynologyDrive-<Drive>).

Non-standard location? Give a full path (starting with / or ~) instead of a name:

Company_Name | ~/SynologyDrive/Company_Name

@host is only used to auto-mount a disconnected SMB share. No reload needed after editing — the script reads the config on every run.

Uninstall

./uninstall.sh            # removes the action and script, keeps your config
./uninstall.sh --purge    # also removes the config

Why "Services" and not a top-level right-click item?

Top-of-the-menu entries (like Dropbox's) require a FinderSync extension — a separate, code-signed app with a Developer ID. That's a lot of moving parts and it breaks on every macOS update. A Quick Action plus a keyboard shortcut does the same job, natively, with nothing to install.

Troubleshooting

First click does nothing / a permission dialog appears. The first time it runs, macOS asks whether Automator (or Finder) may control Finder. Click OK. If you missed it, enable it under System Settings → Privacy & Security → Automation.

"Not in any mapped folder". The item isn't under any pair in your config. Open ~/.config/synology-swap/config.txt and add it. The SMB share name and the Synology Drive folder name must both be listed on one line.

"Could not mount ...". Your Mac has no saved credentials for that share. Mount it once from Finder (Go → Connect to Server) and tick "Remember this password" in Keychain, then it works from then on.

Older Synology Drive setups. If your synced folder lives at ~/SynologyDrive/<name> instead of ~/Library/CloudStorage/SynologyDrive-<name>, the wizard won't auto-detect it. Put a full path in the config instead of a name: ShareName | ~/SynologyDrive/ShareName.

Compatibility

macOS only. Needs the Synology Drive Client and SMB access to the same shares. A Windows (File Explorer) version is on the roadmap.

How it works

• synology-swap.sh — all the logic (mapping + reveal/focus + auto-mount). ./synology-swap.sh --selftest checks the path mapping.
• A Finder Quick Action (~/Library/Services/Synology Swap.workflow) — a thin wrapper that just calls the script.
• ~/.config/synology-swap/config.txt — your folder pairs.

Written for the stock macOS /bin/bash (3.2) — no dependencies, nothing to install.

Support & roadmap

If this saves you some clicks, you can buy me a coffee: Ideas for later (PRs and suggestions welcome):

• Multiple servers / hosts in one config
• "Copy counterpart path" instead of revealing it
• Optional: open a folder into it vs. select it in its parent
• Auto-refresh the mapping when you add a new shared folder
• A menu-bar helper for people who don't want a keyboard shortcut

License

MIT — do whatever, no warranty.