Script Filter XML Format
Note: The XML format has now been deprecated, and we recommend using JSON for script filters, but the XML format will remain available for legacy use.
Example XML Format:
<?xml version="1.0"?>
<items>
<item uid="desktop" arg="~/Desktop" valid="YES" autocomplete="Desktop" type="file">
<title>Desktop</title>
<subtitle>~/Desktop</subtitle>
<icon type="fileicon">~/Desktop</icon>
</item>
</items>A Script Filter is required to return an <items> list of one or more <item>. 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>.
Item Attributes
There are some important attributes you need to populate for Alfred to understand a little more about this result item. This is an example <item> tag with all attributes populated:
<item uid="desktop" arg="~/Desktop" valid="YES" autocomplete="Desktop" type="file">
The attributes are as follows...
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.
arg : STRING (recommended)
The argument which is passed through the workflow to the connected output action.
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.
valid : yes | no (optional, default = "yes")
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.
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="no", 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".
Item Elements
The item elements tell Alfred how you want your <item> to display in Alfred's default results.
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>Home Folder</title>
subtitle
The subtitle displayed in the result row. This element is optional.
<subtitle>Home folder ~/</subtitle>
With your script filter, you have control over the subtext shown when a modifier key is pressed with the subtitle's mod attribute.
<subtitle mod="shift">Subtext when shift is pressed</subtitle>
<subtitle mod="fn">Subtext when fn is pressed</subtitle>
<subtitle mod="ctrl">Subtext when ctrl is pressed</subtitle>
<subtitle mod="alt">Subtext when alt is pressed</subtitle>
<subtitle mod="cmd">Subtext when cmd is pressed</subtitle>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>alfredhat.png</icon>
You can also use the type attribute to alter the way Alfred loads the icon; "fileicon" loads the icon for the specified file and "filetype" loads the icon for the specified system type.
<icon type="fileicon">~/Desktop</icon>
<icon type="filetype">public.jpeg</icon>mod (optional, flexible version of mod attribute of subtitle element)
The mod element gives you more 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.
<mod key="shift" subtitle="New subtext when shift is pressed" valid="yes" arg="shiftmod"/>arg (optional)
Optionally, you can define your argument as an item element instead of an item attribute. If you define the arg element, this will take precedent over an arg attribute defined for this item.
<arg>~/Desktop</arg>
text (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 type="copy">Text when copying</text>
<text type="largetype">Text for LargeType</text>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 (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/</quicklookurl>Variables / Session Variables
A list of variables can be passed out of the script filter within a <variables> tag. 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 require a name attribute:
<variable name="fruit">banana</variable>Note: To keep the XML valid, wrap the entire XML in <output> tags:
<?xml version="1.0"?>
<output>
<variables>
<variable name="fruit">banana</variable>
<variable name="vegetable">carrot</variable>
</variables>
<items>
...
</items>
</output>See the built in "Advanced Script Filter" getting started guide for more info, and to see this in practice.
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.
<?xml version="1.0"?>
<output>
<rerun>1</rerun>
<items>
...
</items>
</output>See the built in "Advanced Script Filter" getting started guide for more info, and to see this in practice.
Escaping the XML
Alfred expects properly escaped XML during parsing. If you don't escape certain characters, your Script Filter may fail and no results will be displayed in Alfred. The characters you will need to escape are:
" "
' '
< <
> >
& &If you are having problems with results not showing in Alfred, use the debug button in the workflow editor which should help identify if your XML has errors. Some languages (or if you are using a framework) will automatically escape the XML. It's worth testing your script output to ensure you don't have escaping problems.
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 <item>s in.
If you would like to control the order of the results and have Alfred present the <item>s in the exact order you return them from your script, exclude the UID attribute, for example:
<item arg="~/Desktop" valid="YES" autocomplete="Desktop" type="file">
An Example
For a working example of the XML format, Add the Getting Started > Script Filter Output workflow from the + button within Alfred's Workflow preferences.
