Invoking Find Any File from other applications via a URL

This web page explains how to invoke FAF from programs such as:

• Alfred
• Keyboard Maestro
• PopClip
• A command line / shell tool (Terminal.app)

Note: This feature requires FAF version 2.3.3 or later.

Basic invocation syntax

Here is an example for a URL that opens FAF and starts a search for "invoice":

fafapp://find?inp=invoice

If you paste the above line into your web browser and press Return, it should open FAF and start the search by filling "invoice" into the first input field (which is, by default: Name contains …).

The same search, but also specifying that the search should be limited to your home folder:

fafapp://find?loc=~&inp=invoice

The same search, searching the entire startup volume, and with swapped inp and loc parameters:

fafapp://find?inp=invoice&loc=/

Some characters have special meaning in the URL, and therefore you cannot directly pass them if you want to search for them in a file name. For instance, if you wanted to find a file name containing a #, %, & or a =, you need to encode them (as %23, %25, %26 and %3D). Furthermore, any blanks (spaces) need to be written as %20.

For example, a search string entered in FAF as text #5 need to be encoded as follows:

fafapp://find?inp=text%20%235

Advanced syntax

The URL consists of a prefix, which is always the same:

fafapp://find?

After this prefix, one or more parameters can be added, each of which has a name (such as inp and loc), followed by an equal sign (=) and a value (which needs to %-encode some characters such as a blank (%20), # (%23), % (%25), & (%26) and = (%3D)).

If more than one parameter gets added, they need to be separated by an ampersand (&).

Thus, opening FAF with both providing an inp and a loc parameter, the entire URL is made up of these parts:

fafapp://find?
  inp
  =
  abc
&
  loc
  =
  /

All joined:

fafapp://find?inp=abc&loc=/

Advanced JSON syntax

Since v2.4, it's also possible to pass the entire rules in JSON format in the URL. Here's the syntax:

fafapp://findjson/jsondata/wmode

Replace jsondata with a JSON string, which you can get from a saved search (.faf file). Since you cannot have literal line delimiters and spaces in a URL, it's best to first remove all line separators (turn the entire .faf contents into a single line) and remove the leading spaces and the spaces around the ":". If any quoted strings contain spaces, it's best to convert them into %20, and convert other "unsafe" URL characters as well, most importantly / into %2F (other unsafe characters, such as { and [ are acceptable by FAF but other program that you pass this URL to may not like them unless you percent-encode them).

Replace wmode with a number that specifies the window mode: 0 will re-use the frontmost Find window, 1 will re-use an unmodified Find window, 2 will always create a new Find window with the search parameters from the JSON data.

Here's an example that searches on the root (startup) volume for names containing "report 2021", appearing in the frontmost Find window (because the wmode was left out, it'll be read as 0), auto starting the search immediately:

fafapp://findjson/{"specs":[{"verb":9,"val":"report%202021","subj":0}],"title":"Name%20contains%20report%202021","autoStart":true,"sources":["%2F"]}

You can copy the above line and paste it into a browser and then hit Return to see it work.

For reference, the above jsondata was created from the following text contents of a saved search (.faf) file:

{
  "specs" : [
    {
      "verb" : 9,
      "val" : "report 2021",
      "subj" : 0
    }
  ],
  "title" : "Name contains report 2021",
  "autoStart" : true,
  "sources" : [
    "/"
  ]
}

Available parameters

inp1, inp2, inp3, …

These fill in the value into the first, or second, third etc., input fields in the Find window. inp is equivalent to inp1.

By default, the Find window only has one input field, for Name contains. However, you can add more rules and then use the menu bar, under File / Save as Default Search to have more input fields by default. Once you have done this, you can fill in these additional fields as well.

Note, however, that you can specify values only for rules that have a textual input field, i.e. where you can type in text or a number. Rules that provide only a pop-up menu, such as Kind and Is a folder, cannot be altered by inp parameters. In order to control these rules, you need to create Search Templates (see below).

If you do not specify any inp parameters, the search will not start automatically.

loc1, loc2, loc3, …

Specifies the location(s) where the search shall take place. loc is equivalent to loc1.

The values can be either:

• A Unix (POSIX) path such as loc=/System, or starting with ~ for the user's home folder (e.g. loc=~/Desktop).
• A file URL such as loc=file:///System (PopClip passes those).
• A classic HFS path such as loc=Macintosh%20HD:System or loc=External%20Disk (there doesn't need to be a colon at the end).
• loc=%230 (or #0): on all disks
• loc=%231 (or #1): on local disks
• loc=%232 (or #2): on network volumes
• loc=%233 (or #3): in Finder selection
• loc=%235 (or #5): on startup disk

If you do not specify this parameter, then the default location of the Find window or of the chosen template (see below) will be used.

win

The value is a number that specifies which Find window shall be used (only relevant if you have FAF already running, with multiple Find windows opened).

• win=0: The frontmost Find window is used (and its input is replaced).
• win=1: The first non-altered Find window is used (i.e. any that you just opened and therefore still contains the default rules).
• win=2: Always opens a new window.

If this parameter is omitted, it acts as if win=0 was provided.

root

root=1 performs the search in root mode.

To make this work, you should have your login+pw saved in the Keychain in order to avoid the login dialog. See the manual.

run, norun

run=0 and norun prevent the search from automatically starting.

run=1 forces the search to start even if no input fields have been filled in.

tpl

Lets you choose a custom Search Template template (see below).

Search Templates

You can prepare special search rules and then use them as templates when filling in the search parameters from the URL.

To create such a template, simply set up the Find window as desired, adding rules as necessary. Then save the Find window by holding down the option key (⌥, alt), while clicking with the mouse into the File menu. Choose the Save as Template… command from the menu. This will bring you directly to the Templates folder (which is at ~/Library/Application Support/Find Any File/Templates). Choose an appropriate but short name for your template and Save.

Now, you can refer to the template by its saved name (omitting the ".faf" extension).

For instance, you could set up a Find window with two rules. The first is: Name contains; the second one: Created date is within the last 1 weeks. Save it under the name "LastWeek" to the Templates folder.

fafapp://find?tpl=LastWeek&inp=invoice

This will open a Find window from the saved template named "LastWeek.faf" before filling in the input fields. Effectively, it'll search for files with "invoice" in their name, created in the last week only.

Here is an example that uses four rules, filling in three of them (rules that have no value are ignored by the search operation):

Special Applications

If you use one of the following programs, you can set them up to invoke FAF with a search string by typing a keyboard shortcut.

Alfred

• Open Alfred's Preferences window.
• In the left panel, click on Workflows.
• Click the [+] button at the bottom and choose from the menu: Templates / Web and URLs / Open custom URL in specified browser. Enter a suitable Name, e.g. "Search with FAF" and click Create.
• Double click on the Keyword icon and enter a shortcut word, e.g. faf, then Save.
• Double click on the Open URL icon and enter the URL: fafapp://find?inp={query}, then Save.

Now, if you invoke Alfred's global input bar, you can type faf invoice, press Return, and FAF will be opened, searching for names with "invoice".

Keyboard Maestro

In the Keyboard Maestro Editor, create a new Macro (cmd-N), add action(s) and fill in the fields as shown below. Once set up, typing ctrl-F will open a window into which you can type a file name you want to find. Pressing Return will then open FAF and start the search for it.

There are two ways to set this up. Either use the simpler "Search the Web" action, or the more complex combination of "Prompt for User Input", "Filter" and "Open a URL", which allows you to build more complex queries, e.g. with multiple input fields.

For a simple search use this:

For building more complex searches, start with the following:

PopClip

Once 2.3 is released (it's still in beta as of the time I'm writing this), PopClip should offer an extension for FAF automatically.

You can also install the extension manually, though. This will also give you the option to specify the name of a saved Search Template (see above) when you install the extension (the one coming from PopClip does not offer this option and will instead always use your default search rules).

Download the extension here.

Once downloaded, double click it to unzip it, then doubleclick the file ending in .popclipext. This should lead to PopClip asking you if you want to trust and install the unsigned extension. If you agree, you will be prompted to enter the name of a Search Template. You can leave it blank to use your default rules.

Now, if you select any text and PopClip's little widget pops up, there are one or two FAF related icons to choose from:

The first icon (showing the letter "a") lets you search for file names matching the selected text.

The second icon, which only appears if you have selected something that looks like a (POSIX) file path, lets you search inside that location (FAF will then start and let you enter what to search for in that location).

Terminal (command line)

The open command can be used to open URLs.

Basically, you'd invoke FAF like this:

open fafapp://find?inp=invoice

If you want to use shell variables and pass them as arguments to FAF, it may get a bit more complicated because you have to escape certain characters. This can be accomplished with invoking a python script, as shown below:

path="#1"  # "on local disks"
what="&"   # search for file names containing an ampersand
enc() { /usr/bin/python -c "import urllib, sys; print urllib.quote(sys.argv[1])" "$1" ; }
/usr/bin/open fafapp://find?loc=$(enc "$path")\&inp=$(enc "$what")

Also note that you have to \-escape the & parameter delimiter.