Script Filter JSON Format

Alfred 3 introduces JSON as the recommended format to return results into Alfred from a Script Filter.

Example JSON Format:

{"items": [
    {
        "uid": "desktop",
        "type": "file",
        "title": "Desktop",
        "subtitle": "~/Desktop",
        "arg": "~/Desktop",
        "autocomplete": "Desktop",
        "icon": {
            "type": "fileicon",
            "path": "~/Desktop"
        }
    }
]}

A Script Filter is required to return an items array of zero or more items. Each item describes a result row displayed in Alfred. The three obvious elements are the ones you see in an Alfred result row - title, subtitle and icon.

Properties

Alfred uses the following properties within each item in the items array:

uid : STRING (optional)

This is a unique identifier for the item which allows help Alfred to learn about this item for subsequent sorting and ordering of the user's actioned results.

It is important that you use the same UID throughout subsequent executions of your script to take advantage of Alfred's knowledge and sorting. If you would like Alfred to always show the results in the order you return them from your script, exclude the UID field.

title

The title displayed in the result row. There are no options for this element and it is essential that this element is populated.

"title": "Desktop"

subtitle

The subtitle displayed in the result row. This element is optional.

"subtitle": "~/Desktop"

arg : STRING (recommended)

The argument which is passed through the workflow to the connected output action.

"arg": "~/Desktop"

While the arg attribute is optional, it's highly recommended that you populate this as it's the string which is passed to your connected output actions. If excluded, you won't know which result item the user has selected.

icon

The icon displayed in the result row. Workflows are run from their workflow folder, so you can reference icons stored in your workflow relatively.

"icon": {
    "type": "fileicon",
    "path": "~/Desktop"
}

By omitting the "type", Alfred will load the file path itself, for example a png. By using "type": "fileicon", Alfred will get the icon for the specified path. Finally, by using "type": "filetype", you can get the icon of a specific file, for example "path": "public.png"

valid : true | false (optional, default = true)

If this item is valid or not. If an item is valid then Alfred will action this item when the user presses return. If the item is not valid, Alfred will do nothing. This allows you to intelligently prevent Alfred from actioning a result based on the current {query} passed into your script.

If you exclude the valid attribute, Alfred assumes that your item is valid.

match : STRING (optional)

From Alfred 3.5, the match field enables you to define what Alfred matches against when the workflow is set to "Alfred Filters Results". If match is present, it fully replaces matching on the title property.

"match": "my family photos"

Note that the match field is always treated as case insensitive, and intelligently treated as diacritic insensitive. If the search query contains a diacritic, the match becomes diacritic sensitive.

This option pairs well with the "Alfred Filters Results" Match Mode option.

autocomplete : STRING (recommended)

An optional but recommended string you can provide which is populated into Alfred's search field if the user auto-complete's the selected result (⇥ by default).

If the item is set as "valid": false, the auto-complete text is populated into Alfred's search field when the user actions the result.

type : "default" | "file" | "file:skipcheck" (optional, default = "default")

By specifying "type": "file", this makes Alfred treat your result as a file on your system. This allows the user to perform actions on the file like they can with Alfred's standard file filters.

When returning files, Alfred will check if the file exists before presenting that result to the user. This has a very small performance implication but makes the results as predictable as possible. If you would like Alfred to skip this check as you are certain that the files you are returning exist, you can use "type": "file:skipcheck".

mods : OBJECT (optional)

The mod element gives you control over how the modifier keys react. You can now define the valid attribute to mark if the result is valid based on the modifier selection and set a different arg to be passed out if actioned with the modifier.

"mods": {
    "alt": {
        "valid": true,
        "arg": "alfredapp.com/powerpack",
        "subtitle": "https://www.alfredapp.com/powerpack/"
    },
    "cmd": {
        "valid": true,
        "arg": "alfredapp.com/powerpack/buy/",
        "subtitle": "https://www.alfredapp.com/powerpack/buy/"
    },
}

From Alfred 3.4.1, you can define an icon and variables for each object in the mods object.

See Variables / Session Variables for more info about using variables.

text : OBJECT (optional)

The text element defines the text the user will get when copying the selected result row with ⌘C or displaying large type with ⌘L.

"text": {
    "copy": "https://www.alfredapp.com/ (text here to copy)",
    "largetype": "https://www.alfredapp.com/ (text here for large type)"
}

If these are not defined, you will inherit Alfred's standard behaviour where the arg is copied to the Clipboard or used for Large Type.

quicklookurl : STRING (optional)

A Quick Look URL which will be visible if the user uses the Quick Look feature within Alfred (tapping shift, or cmd+y). Note that quicklookurl will also accept a file path, both absolute and relative to home using ~/.

"quicklookurl": "https://www.alfredapp.com/"

Variables / Session Variables

Variables can be passed out of the script filter within a variables object. This is useful for two things. Firstly, these variables will be passed out of the script filter's outputs when actioning a result. Secondly, any variables passed out of a script will be passed back in as environment variables when the script is run within the same session. This can be used for very simply managing state between runs as the user types input or when the script is set to re-run after an interval.

{
    "variables": {
        "fruit": "banana",
        "vegetable": "carrot"
    }
    "items": [
        ...
    ]
}

See the built in "Advanced Script Filter" getting started guide for more info, and to see this in practice.

Item Variables

From Alfred 3.4.1, individual item objects can also have variables which are passed out of the Script Filter object if the associated Result Item is selected in Alfred's results list. variables set within an item will override any JSON session variables of the same name.

It is also possible to set additional variables for each mod object within an item. variables set for a mod will override any item variables of the same name.


Rerunning script filters automatically

Scripts can be set to re-run automatically after an interval using the 'rerun' key with a value of 0.1 to 5.0 seconds. The script will only be re-run if the script filter is still active and the user hasn't changed the state of the filter by typing and triggering a re-run.

{
    "rerun" : 1,
    "items": [
        ...
    ]
}

See the built in "Advanced Script Filter" getting started guide for more info, and to see this in practice.


Result Ordering and the UID

It's worth reiterating that Alfred learns usage of your item results just as he learns any other type of result a user actions within Alfred. As such, the order Alfred presents your workflow results will be based on Alfred's knowledge using the item UID and not the order you return the items in.

If you would like to control the order of the results and have Alfred present the items in the exact order you return them from your script, exclude the UID attribute, for example:

{"items": [
    {
        "type": "file",
        "title": "Desktop",
        "subtitle": "~/Desktop",
        "arg": "~/Desktop",
        "autocomplete": "Desktop",
        "icon": {
            "type": "fileicon",
            "path": "~/Desktop"
        }
    }
]}

An Example

For a working example of the JSON format, Add the Getting Started > Script Filter Output workflow from the + button within Alfred's Workflow preferences.

Latest Blog Post:

Alfred 3.5 Released: New Bookmarks Feature, High Sierra Support and More

CacheFly Campaign Monitor

"Alfred" is a registered trademark of Running with Crayons Ltd. ©2017 Running with Crayons Ltd. All rights reserved.

Terms & Conditions, Privacy Policy, Cookies.