Roey BiranDesigner + Developer

Help

Table of Contents

User Guide

How Searching Works

In Finbar, every menu item is matched by its title, while nested menu items below a certain depth are also matched by the title of their containing menu item. This is similar to how the built–in menu bar searching operates. For those nested menu items, their title will be preceded by the one of its parent. Accordingly, the respective parent’s title will not be shown in the location column.

Searching vs. Browsing

Finbar operates in two implicit “modes” — searching and browsing. The app enters searching mode whenever you type something in search field. Appropriately, you return to browsing mode by clearing the search field.

The differences between these two modes are:

SearchingBrowsing
Items are a flat listItems are a browsable outline
Nested (above a certain level) menu items’ titles are preceded by the parent’s titleAll titles shown as they are

When activating a “container” menu item, you enter a new, scoped context that can be further browsed or searched. The differences noted above still apply.

There’s another special ”mode” worth mentioning. You enter it when the search field is empty and you’re not in a scoped context. This is the state when the app activates.

In this mixed mode, items in some sections (like recents) may have their title preceded by their container’s title (depending on their nesting level), and they are not browsable; while items other sections may still appear as an outline and are browsable.

Using the Rule Editor

Finbar’s rule editor uses the Mac’s standard rule editing component and thus would work as you’d expect (for a primer on macOS rule editors, see this Apple support article). There’re however a few special considerations to take into account when matching by the following criteria, which are unique to Finbar:

  1. Menu item’s path: Path components should be separated with a backslash (\). For example, to exclude Safari’s “View > Translation” menu item, specify the path as “View\Translation” (without the quotes).
  2. Menu item’s index: The index in question refers to the menu item’s position among its neighboring menu items inside a given menu. The first menu item in that menu would have an index of 1. Note that separators between menu items should also be included in the count. For example, to exclude Safari’s “Edit > Cut” menu item, specify an index of 4 (that’s because it follows 3 menu items — “Undo“, “Redo”, and a separator).
  3. Menu item’s depth: Menu bar items have a depth of 0, and each submenu increases that depth by 1. For example, to exclude Safari’s “File > Export > Bookmarks…” menu item, specify a depth of 2.

Command–line Interface

Finbar includes an executable tool offering a command–line interface to some of its basic functionalities. It’s located within the application bundle, at the following path: Finbar.app/Contents/MacOS/finbar-cli. For usage instructions and help, run:

finbar-cli -h

Adding Scripts

Any valid script — that is, any text file with an interpreter directive (or shebang) supported by your system — can be used to extend Finbar.

To add a script:

  1. Create the following directory: ~/Library/Application Scripts/com.roeybiran.Finbar. The tilde is an alias to your home directory.
  2. Create a sub–folder named with the app’s bundle identifier. For example, a folder for scripts specific to Safari should have the following path: ~/Library/Application Scripts/com.roeybiran.Finbar/com.apple.Safari.
  3. Put your script inside the sub–folder you’ve just created. For example, A Safari–only AppleScript script named “Close Tabs to the Right” should have the following path: ~/Library/Application Scripts/com.roeybiran.Finbar/com.apple.Safari/Close Tabs to the Right.scpt.

Any scripts you add will be added to the search result on Finbar’s next launch. To do that immediately, click the “Reload Scripts” menu item in the options menu.

Activating Programmatically

It’s possible to programmatically open Finbar without stealing focus from the frontmost application, with the following shell command:

open -ga Finbar

A use case for this feature is to activate Finbar from a specialized automation tool such as Karabiner–Elements or BetterTouchTool, which can run shell scripts in various ways, such as double–tapping a modifier key.

Troubleshooting

If you can’t find a specific menu item, or any menu items at all

First, try finding the desired menu item with the Mac’s standard search feature first. If this fails, it’s likely that the app has a non–standard implementation of the menu bar (for example, menu items lack the standard attributes Finbar uses for searching). It would be best to report this to the app’s developer, but you could also submit an issue and we’ll try to find a workaround.

If you did manage to find what you’ve been looking for using the regular search feature, it’s a problem within Finbar and I‘d appreciate it if you’d submit an issue.

If selecting a menu item does nothing

First, find and select (with the keyboard) the desired menu item using the Mac’s regular menu bar search feature. If this does nothing as well, the problem is most likely with the target app itself — some apps implement the menu bar clicking mechanisms in a non–standard way. Consider reporting this to the app’s developer.

However, if selecting the menu item did seem to work, the problem lies within Finbar and/or the way it works with the other app. Please submit an issue.

Privacy Policy

Finbar requires your consent to use your Mac’s accessibility features to search the menu bar and perform “clicks” on menu items when necessary. It retrieves the bare minimum of menu item attributes needed for the search experience, and all of that data is stored privately on your Mac. No other personal information or data is consumed by the app, in any way.