AwGo — A Go library for Alfred workflows

Full-featured library to build lightning-fast workflows in a jiffy.

Features

• Easy access to Alfred and workflow settings.
• Fluent API for generating Alfred JSON feedback for Script Filters.
• Support for all applicable Alfred features up to v3.6.
• Fuzzy sorting/filtering of results.
• Simple, but powerful, API for caching/saving workflow data.
• Catches panics, logs stack trace and shows user an error message.
• Workflow update API with built-in support for GitHub releases.
• Pre-configured logging for easier debugging, with a rotated log file.
• "Magic" queries/actions for simplified development and user support.
• macOS system icons.

Installation & usage

Install AwGo with:

go get -u github.com/deanishe/awgo

Typically, you'd call your program's main entry point via Workflow.Run(). This way, the library will rescue any panic, log the stack trace and show an error message to the user in Alfred.

program.go:

package main

// Package is called aw
import "github.com/deanishe/awgo"

// Workflow is the main API
var wf *aw.Workflow

func init() {
    // Create a new Workflow using default settings.
    // Critical settings are provided by Alfred via environment variables,
    // so this *will* die in flames if not run in an Alfred-like environment.
    wf = aw.New()
}

// Your workflow starts here
func run() {
    // Add a "Script Filter" result
    wf.NewItem("First result!")
    // Send results to Alfred
    wf.SendFeedback()
}

func main() {
    // Wrap your entry point with Run() to catch and log panics and
    // show an error in Alfred instead of silently dying
    wf.Run(run)
}

In the Script Filter's Script box (Language = /bin/bash with input as argv):

./program "$1"

Documentation

Read the docs on GoDoc.

Check out the example workflows (docs), which show how to use AwGo. Use one as a template to get your own workflow up and running quickly.

Requirements

The library (and therefore the unit tests) rely on being run in a minimally Alfred-like environment, as they pull configuration options from the environment variables set by Alfred.

This means that if you want to run AwGo-based code outside Alfred, e.g. in your shell, you must set at least the following environment variables to meaningful values, or the library will panic:

• alfred_workflow_bundleid
• alfred_workflow_cache
• alfred_workflow_data

And if you're using the update API, also:

• alfred_workflow_version

Development

To create a sufficiently Alfred-like environment, you can source the env.sh script in the project root or run unit tests via the run-tests.sh script (which also sets up an appropriate environment before calling go test).

Licensing & thanks

This library is released under the MIT licence.

The icon is based on the Go Gopher by Renee French.