Finbar Help

User Guide

How Searching Works

In Finbar, every item is matched by its title. Additionally, menu items below a certain depth are also matched by the title of the containing menu. This is similar to the way the built-in menu bar searching works.

Disabled Menu Items

Finbar displays and allows the selection of disabled menu items, which will have a dimmed appearance.

The rationale to this is as follows: some apps disable some of their menu items when they lose keyboard focus. In other words, these menu items are disabled only while viewed in Finbar - they’ll be re-enabled by the respective app once Finbar initiates a menu item click and deactivates. Thus, guarding against selection of disabled menu items means leaving out many that are perfectly valid.

Some menu items are disabled regardless of focus and will remain so after Finbar deactivates. Selecting them will trigger a system notification alerting you of this.

List Mode and Outline Mode

Finbar can show menu items in two ways: list mode and outline mode. You can switch between them at any time, and Finbar keeps your current search intact.

The differences are:

Narrowing the Search Scope

If the current selection is a container item, you can narrow the search to that submenu and keep going from there. The scope bar above the search field shows where you are. To leave the current scope, press Backspace while the query is empty or click the scope bar’s clear button.

The Root Screen

The root screen is Finbar’s default state. You return to it by clearing the search field and leaving any active scope. Here, Recents appear as a simple list, while the menu bar itself remains available in outline mode.

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.

Finbar vs. the Mac’s Built-in Menu Bar Search

The Mac’s built–in menu bar search has no fuzzy filtering; it also searches through the menu bar owning app’s “help book” which slows things down considerably. It doesn’t remember your recently selected menu items, and it offers no control over excluding or including specific menu items from search results, and offers no inherent appearance customization or extendability options.