Alfred-Workflow

A helper library in Python for authors of workflows for [Alfred 3 and 4][alfred].

[![Build Status][shield-github]][action-github] [![Coverage Status][shield-coveralls]][coveralls] [![Development Status][shield-status]][pypi] [![Latest Version][shield-version]][pypi] [![Supported Python Versions][shield-pyversions]][pypi]

Supports Alfred 3 and Alfred 4 on macOS 10.7+ (Python 2.7).

Alfred-Workflow takes the grunt work out of writing a workflow by giving you the tools to create a fast and featureful Alfred workflow from an API, application or library in minutes.

Always supports all current Alfred features.

Features

• Auto-saved settings API for your workflow
• Super-simple data caching with expiry
• Fuzzy filtering (with smart diacritic folding)
• Keychain support for secure storage of passwords, API keys etc.
• Lightweight web API with [Requests][requests]-like interface
• Background tasks to keep your workflow responsive
• Simple generation of Alfred JSON feedback
• Full support of Alfred's AppleScript/JXA API
• Catches and logs workflow errors for easier development and support
• "Magic" arguments to help development/debugging
• Unicode support
• Pre-configured logging
• Automatically check for workflow updates via GitHub releases
• Post notifications via Notification Center

Alfred 4+ features

• Advanced modifiers
• Alfred 4-only updates (won't break older Alfred installs)

Contents

• Installation
  • With pip
  • From source
• Usage
  • Workflow script skeleton
  • Examples
    • Web
    • Keychain access
• Documentation
  • Dash docset
• Licensing, thanks
• Contributing
  • Adding a workflow to the list
  • Bug reports, pull requests
  • Contributors
• Workflows using Alfred-Workflow

Installation

Note: If you're new to Alfred workflows, check out [the tutorial][docs-tutorial] in the docs.

With pip

You can install Alfred-Workflow directly into your workflow with:

# from your workflow directory
pip install --target=. Alfred-Workflow

You can install any other library available on the [Cheese Shop][cheeseshop] the same way. See the [pip documentation][pip-docs] for more information.

It is highly advisable to bundle all your workflow's dependencies with your workflow in this way. That way, it will "just work".

From source

1. Download the alfred-workflow-X.X.X.zip from the [GitHub releases page][releases].
2. Extract the ZIP archive and place the workflow directory in the root folder of your workflow (where info.plist is).

Your workflow should look something like this:

Your Workflow/
    info.plist
    icon.png
    workflow/
        __init__.py
        background.py
        notify.py
        Notify.tgz
        update.py
        version
        web.py
        workflow.py
    yourscript.py
    etc.

Alternatively, you can clone/download the Alfred-Workflow [repository][repo] and copy the workflow subdirectory to your workflow's root directory.

Usage

A few examples of how to use Alfred-Workflow.

Workflow script skeleton

Set up your workflow scripts as follows (if you wish to use the built-in error handling or sys.path modification):

#!/usr/bin/python
# encoding: utf-8

import sys

# Workflow3 supports Alfred 3's new features. The `Workflow` class
# is also compatibl