FileRouter Help

Make FileRouter the default handler

Install FileRouter into /Applications. Quit any older copy so only one menu bar icon is running.

FileRouter only handles types you assign to it. For each route you care about (Markdown, Plain Text, or a custom type), open that route’s submenu in the menu bar and choose Make FileRouter default. macOS may ask you to confirm per type; after that, double-clicked files of that type land in FileRouter first — then FileRouter opens the editor your rules select.

Adding a custom type (see below) also claims FileRouter as the default for that type after you confirm. You still use Make FileRouter default on a route’s submenu if you want to re-claim an existing route later.

If a specific type still opens elsewhere, check Finder’s Get Info → Open with for that file, or run Make FileRouter default again from that route’s submenu.

Setting a default editor

The menu bar shows one submenu per route (Markdown, Plain Text, and any custom types). Each submenu lists the editors enabled for that route; the active item is the route default.

In Settings → Editors, curate which discovered apps appear for each route. Use Add App… for apps that Launch Services never offers (for example apps that open folders rather than files). Viewer-only apps stay disabled until you enable them. Select All / Deselect All turn every Offer checkbox on or off for the current file type in one step.

The permanent Default Rule on the Rules tab always opens that same fallback editor. Changing the menu pick or the Default Rule’s editor updates the other.

Picker utilities

When a rule shows the interactive picker (list or radial), FileRouter can offer utility actions below the editors — still per file type, not app-wide. Choosing a utility does not open an editor; the picker can return a utility choice even when no app is selected.

Built-in utilities

In Settings → Editors, under Utilities in the picker, enable any of:

• Copy POSIX Path — copies the selected file path(s) to the pasteboard (newline-joined when several files are opened together).
• Reveal in Finder — selects the file(s) in Finder.
• Open Parent in Terminal — opens each file’s unique parent folder in a terminal app you choose (default Terminal.app). Use the popup or Other… to pick iTerm, Warp, Kitty, and so on.

Enabled built-in utilities appear in both the list picker (separated from editors) and the radial picker (as their own slices).

Shortcuts, Services, and AppleScripts

The same Utilities section can also offer Run Shortcuts…, Run Services…, and Run AppleScripts…. Each opens a checklist for the current file type; everything starts unchecked.

• Shortcuts — choose which Shortcuts appear for this route. At run time, FileRouter passes the current file(s) into the shortcut.
• Services — choose file/folder-capable system Services. They receive the current file URLs.
• AppleScripts — choose scripts from your Scripts folder (see below). Plain AppleScripts (.applescript / .scpt) get POSIX paths as argv (on run argv). Automator workflows (.workflow) use Automator-style file input.

Enabled items appear:

• In the list picker and status menu, under Run Shortcuts, Run Services, and Run AppleScripts submenus (empty groups are omitted).
• In the radial picker, as named slices (display names without file extensions).

Scripts folder

Use Open Scripts Folder in the Utilities section to create or reveal the active scripts directory:

• Direct / Setapp — ~/Library/Scripts
• Mac App Store — Application Scripts for FileRouter (install/manage via Settings when prompted)

Drop .applescript, .scpt, or .workflow files there (subfolders are fine). FileRouter scans recursively; menu labels strip the extension.

Example AppleScript that receives paths as argv:

on run argv
repeat with p in argv
-- do something with POSIX path p
end repeat
end run

If a shortcut, service, or script fails at run time, FileRouter shows a brief alert; the item stays enabled so you can fix the target and try again.

Folder-specific “always open in this app” behavior still belongs on Rules (for example a parent-folder condition with Always open). Utilities are for one-shot actions from the picker or status menu.

Editing Rules

Open Settings → Rules. Rules are ordered per route; the first enabled matching rule wins.

Combine conditions with AND/OR. Conditions can include file name, extension, parent folder (subtree), creator app metadata, and how many of the route’s enabled editors are currently running.

You can also assign a hotkey to a rule (for example Shift-Command-F1). Hotkeys are recorded global shortcuts that route the current file selection when pressed — they are not “held while opening” modifiers, which conflict with Finder’s own modifier behavior. Letter shortcuts need Command so Finder does not treat them as type-ahead; function keys do not. Hotkey chords are stored in preferences, not in routes.json — see Copying settings to another Mac.

Actions can open a specific editor, the route default, the best running editor (from a preference list), or show a HUD to pick from all / running enabled editors. When the HUD appears, any built-in utilities and enabled Shortcuts, Services, or AppleScripts for that route are available alongside the editors (see Picker utilities).

Every route ends with a permanent Default Rule (no criteria) that cannot be reordered, disabled, or removed. Legacy Path Rules migrate automatically into equivalent folder rules.

Custom file types

Drop an unrouted file onto FileRouter, or use Add Type… in Settings, to teach a new type from the file’s extension and UTI. You can also drag a file over the menu bar icon and drop it on the Route File Type palette.

If the type overlaps an existing route, FileRouter offers a merge instead of a duplicate. Custom types can be removed; built-in routes cannot. After you confirm, FileRouter claims default-handler status for the new type (macOS may prompt). Then pick an editor for that route in Settings.

Editor open URL templates

On an Editors row, open the gear to attach an optional open URL. When set, FileRouter always opens that editor via the expanded URL (a URL badge appears on the row).

Placeholders: {filepath}, {folderpath}, {filename}, tilde forms {filepath~} / {folderpath~}, and .urlencoded variants of each.

Example for nvUltra:

x-nvultra://open?notebook={folderpath~.urlencoded}&note={filename.urlencoded}

Opening files with the URL scheme

FileRouter registers the custom URL scheme x-filerouter. Use it from Terminal, scripts, Shortcuts, or any app that can open URLs, to send files into FileRouter—and optionally force a specific rule’s action.

This is different from making FileRouter the default app for a file type. open /path/to/file.md still works when FileRouter is the handler. The URL scheme is for when you want an explicit invoke, especially when you need a named rule.

Basic open

Open a file through FileRouter’s normal routing (rules top to bottom, then the Default Rule):

open 'x-filerouter://open?file=/Users/you/Notes/draft.md'

Force a specific rule

Add a rule parameter to run that rule’s action even if its When conditions would not match:

open 'x-filerouter://open?file=/Users/you/Notes/draft.md&rule=New%20Rule'

Or use the rule’s stable ID (preferred for scripts):

open 'x-filerouter://open?file=/Users/you/Notes/draft.md&rule=550e8400-e29b-41d4-a716-446655440000'

URL-only rules

Because a forced URL ignores When and can target a disabled rule, you can keep a rule in the list solely for scripting: leave it disabled so it never matches on drop/open/hotkey, and invoke it only with x-filerouter://open?…&rule=… (preferably by Copy Rule ID).

URL shape

x-filerouter://open?file=<absolute-path>
x-filerouter://open?file=<absolute-path>&rule=<id-or-name>
x-filerouter://open?file=<path1>&file=<path2>&rule=<id-or-name>

Notes:

• Paths must be absolute (start with /). Relative paths and ~/… are not expanded.
• Spaces and special characters in paths or rule names must be percent-encoded (for example a space becomes %20).
• Use a path, not a nested file:// URL inside file=.

How rule= is resolved

1. FileRouter finds the route for that file’s type (Markdown, HTML, and so on), the same as a normal open.
2. It looks for a rule on that route only:
   • First: a rule whose ID equals rule=
   • Otherwise: exactly one rule whose display name equals rule= (case-sensitive)
3. If it finds a match, it runs that rule’s action. When is ignored. Always Open / Default Rule do not override a forced rule.
4. If it cannot resolve the rule (unknown, on another file type’s route, or two rules share the same name), FileRouter beeps and skips that file—it does not fall back to normal matching.

Disabled rules can still be forced. Turn a rule off in Settings so it never runs during normal opens or hotkeys, but keep calling it with rule= when you want it. That makes a rule effectively URL-only: it exists for scripts and x-filerouter:// links, not for everyday routing.

Getting a rule ID or a ready-made URL

In Settings → Rules:

1. Select a file type in the sidebar.
2. Right-click (or Control-click) a rule in the list.
3. Choose:

   • Copy Rule ID — copies the stable ID (best for scripts; survives renames).

   • Copy URL Scheme Template — copies something like:

     x-filerouter://open?rule=<id>&file=

     Paste a full absolute path after file= (encode spaces if needed), then open the URL.

The Default Rule row has no ID and does not offer these copy actions.

Examples

# Normal routing for one Markdown file
open 'x-filerouter://open?file=/Users/you/Notes/draft.md'

# Force the rule named "Blog Post" on that file’s route
open 'x-filerouter://open?file=/Users/you/Notes/draft.md&rule=Blog%20Post'

# Two files, same forced rule (by ID)
open 'x-filerouter://open?file=/Users/you/a.md&file=/Users/you/b.md&rule=550e8400-e29b-41d4-a716-446655440000'

From a shell script that builds the URL safely:

FILE="/Users/you/Notes/My Draft.md"
RULE_ID="550e8400-e29b-41d4-a716-446655440000"
ENCODED_FILE=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe="/"))' "$FILE")
open "x-filerouter://open?file=${ENCODED_FILE}&rule=${RULE_ID}"

Troubleshooting

FileRouter does not handle http or https links. Only x-filerouter://open is supported for this feature.

Copying settings to another Mac

There is no export/import button yet. You can still move your setup by copying the settings file. Quit FileRouter on both Macs first so nothing is writing to the file while you copy.

Where the file lives

The routing document is routes.json. The folder depends on which edition you installed:

• Direct (website download) and Setapp — ~/Library/Application Support/FileRouter/routes.json
• Mac App Store — ~/Library/Containers/com.brettterpstra.FileRouter/Data/Library/Application Support/FileRouter/routes.json

Copy that file to the matching location on the other Mac, then launch FileRouter. Direct and Setapp can share the same Application Support folder on one computer; the Mac App Store build uses its sandbox container instead.

In Finder, Go → Go to Folder… (⇧⌘G) and paste the path if the Library folder is hidden.

What routes.json includes

• Custom file types (and merged extensions / UTIs)
• Per-type editor lists, which apps are offered, the active/fallback editor, and “open enclosing folder” flags
• Preference order for interactive pick / best-running
• All routing rules (conditions, actions, Always Open lists, Default Rule mode)
• Editor open URL templates
• Which picker utilities are offered per type (Copy POSIX Path, Reveal in Finder, Open Parent in Terminal, and the enabled Shortcuts / Services / AppleScripts checklists)

What does not come along

These stay on the original Mac unless you copy extra files or set them again:

• Make FileRouter default — that is a Finder / Launch Services setting per Mac. Run Make FileRouter default on each route you care about after the copy.
• Rule hotkeys — the chord itself is stored in FileRouter’s preferences, not in routes.json. The rule still exists after a copy, but you will need to record the shortcut again unless you also copy the preferences file (below).
• General Settings such as list vs radial picker (and the VoiceOver radial option).
• Installed apps — editors, Shortcuts, Services, and scripts only work if the same apps and files exist on the other Mac. Missing editors simply do not appear until you install them (or use Add App…).
• Mac App Store helper scripts — if you use AppleScripts from Settings on the App Store build, those files live under Application Scripts for FileRouter, not in routes.json. Direct and Setapp use ~/Library/Scripts, which is already a user folder you may sync separately.
• License (Direct) — do not copy license or purchase files. Activate that Mac with FileRouter → License….
• Permissions — Accessibility and Automation consent are per Mac.

Optional: also copy preferences (hotkeys and General)

If you use rule hotkeys or want picker style to match, quit FileRouter and copy the preferences plist as well:

• Direct / Mac App Store — ~/Library/Preferences/com.brettterpstra.FileRouter.plist
  On the App Store build this file is inside the container:
  ~/Library/Containers/com.brettterpstra.FileRouter/Data/Library/Preferences/com.brettterpstra.FileRouter.plist
• Setapp — ~/Library/Preferences/com.brettterpstra.FileRouter-setapp.plist

Replace the file on the destination Mac only after quitting FileRouter there. Mixing a Direct plist onto a Setapp install (or the reverse) will not map correctly because the bundle IDs differ.

There is no supported live sync (iCloud Drive on Application Support while FileRouter is running). Copy while both copies are quit, then relaunch on the destination.