Overview

Build Status Code Coverage Latest Version Development Status Supported Python Versions

Go to Quick Index.

Alfred-Workflow is a Python helper library for Alfred 2 and 3 workflow authors, developed and hosted on GitHub.

Alfred workflows typically take user input, fetch data from the Web or elsewhere, filter them and display results to the user. Alfred-Workflow takes care of a lot of the details for you, allowing you to concentrate your efforts on your workflow’s functionality.

Alfred-Workflow supports OS X 10.6+ (Python 2.6 and 2.7).

Features

Alfred 3-only features

  • Set workflows variables from code
  • Advanced modifiers
  • Alfred 3-only updates (won’t break Alfred 2 installs)

Quick example

Here’s how to show recent Pinboard.in posts in Alfred.

Create a new workflow in Alfred’s preferences. Add a Script Filter with Language /usr/bin/python and paste the following into the Script field (changing API_KEY):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import sys
from workflow import Workflow, ICON_WEB, web
# To use Alfred 3's feedback mechanism:
# from workflow import Workflow3

API_KEY = 'your-pinboard-api-key'

def main(wf):
    url = 'https://api.pinboard.in/v1/posts/recent'
    params = dict(auth_token=API_KEY, count=20, format='json')
    r = web.get(url, params)
    r.raise_for_status()
    for post in r.json()['posts']:
        wf.add_item(post['description'], post['href'], arg=post['href'],
                    uid=post['hash'], valid=True, icon=ICON_WEB)
    wf.send_feedback()


if __name__ == u"__main__":
    wf = Workflow()
    sys.exit(wf.run(main))

Add an Open URL action to your workflow with {query} as the URL, connect your Script Filter to it, and you can now hit ENTER on a Pinboard item in Alfred to open it in your browser.

Warning

Using the above example code as a workflow will likely get you banned by the Pinboard API. See the Tutorial if you want to build an API terms-compliant (and super-fast) Pinboard workflow.

Supported software

Alfred-Workflow supports all versions of Alfred 2 and all versions of OS X supported by Alfred 2. It works with Python 2.6 and 2.7, but not Python 3.

Some features are not available on older versions of OS X.

Installation

Alfred-Workflow can be installed from the Python Package Index with pip or from the source on GitHub.

The Alfred-Workflow Tutorial

A two-part tutorial on writing an Alfred workflow with Alfred-Workflow, taking you through the basics to a performant and release- ready workflow. This is the best starting point for workflow authors new to Python or programming in general. More experienced Python coders should skim this or skip straight ahead to the User Manual.

API documentation

Documetation of the Alfred-Workflow APIs generated from the source code. A handy reference if (like me) you sometimes forget parameter names.

Script Filter results and the XML format

An in-depth look at Alfred’s XML format, the many parameters accepted by Workflow.add_item() and how they interact with one another.

Note

This should also serve as a decent reference to Alfred’s XML format for folks who aren’t using Alfred-Workflow. The official Alfred 2 XML docs have recently seen a massive update, but historically haven’t been very up-to-date.

Workflows using Alfred-Workflow

This is a list of some of the workflows based on Alfred-Workflow.

Feedback, questions, bugs, feature requests

If you have feedback or a question regarding Alfred-Workflow, please post in them in the Alfred forum thread.

If you have a bug report or a feature request, please create a new issue on GitHub.

You can also email me at deanishe@deanishe.net with any questions/feedback/bug reports. However, it’s generally better to use the forum/GitHub so that other users can benefit from and contribute to the conversation.

Quick Index

The Quick Index is a list of links to all the interesting parts of the documentation.

Indices and tables