README.md

AwGo — A Go library for Alfred workflows

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

• Features
• Installation & usage
• Documentation
• Requirements
• Development
• Licensing & thanks

Features

• Full support for Alfred 3 & 4
• Bi-directional interface to workflow's config
• Fluent API for generating Script Filter JSON
• Fuzzy sorting/filtering
• Simple, powerful API for caching/saving workflow data
• Keychain API to securely store (and sync) sensitive data
• Helpers to easily run scripts and script code
• Workflow update API with built-in support for GitHub & Gitea
• Pre-configured logging for easier debugging, with a rotated log file
• Catches panics, logs stack trace and shows user an error message
• "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 pkg.go.dev.

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
• alfred_version (not needed for Alfred 4+)

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. It was built with neovim and GoLand by JetBrains.

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