Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


Package aw is a utility library/framework for Alfred 3 workflows It provides APIs for interacting with Alfred (e.g. Script Filter feedback) and the workflow environment (variables, caches, settings). NOTE: AwGo is currently in development. The API *will* change and should not be considered stable until v1.0. Until then, vendoring AwGo (e.g. with dep or vgo) is strongly recommended. As of AwGo 0.14, all applicable features of Alfred 3.6 are supported. The main features are: Typically, you'd call your program's main entry point via Run(). This way, the library will rescue any panic, log the stack trace and show an error message to the user in Alfred. In the Script box (Language = "/bin/bash"): To generate results for Alfred to show in a Script Filter, use the feedback API of Workflow: You can set workflow variables (via feedback) with Workflow.Var, Item.Var and Modifier.Var. See Workflow.SendFeedback for more documentation. Alfred requires a different JSON format if you wish to set workflow variables. Use the ArgVars (named for its equivalent element in Alfred) struct to generate output from Run Script actions. Be sure to set TextErrors to true to prevent Workflow from generating Alfred JSON if it catches a panic: See ArgVars for more information. New() creates a *Workflow using the default values and workflow settings read from environment variables set by Alfred. You can change defaults by passing one or more Options to New(). If you do not want to use Alfred's environment variables, or they aren't set (i.e. you're not running the code in Alfred), you must pass an Env as the first Option to New() using CustomEnv(). A Workflow can be re-configured later using its Configure() method. Check out the _examples/ subdirectory for some simple, but complete, workflows which you can copy to get started. See the documentation for Option for more information on configuring a Workflow. AwGo can filter Script Filter feedback using a Sublime Text-like fuzzy matching algorithm. Workflow.Filter() sorts feedback Items against the provided query, removing those that do not match. Sorting is performed by subpackage fuzzy via the fuzzy.Sortable interface. See _examples/fuzzy for a basic demonstration. See _examples/bookmarks for a demonstration of implementing fuzzy.Sortable on your own structs and customising the fuzzy sort settings. AwGo automatically configures the default log package to write to STDERR (Alfred's debugger) and a log file in the workflow's cache directory. The log file is necessary because background processes aren't connected to Alfred, so their output is only visible in the log. It is rotated when it exceeds 1 MiB in size. One previous log is kept. AwGo detects when Alfred's debugger is open (Workflow.Debug() returns true) and in this case prepends filename:linenumber: to log messages. The Config struct (which is included in Workflow as Workflow.Config) provides an interface to the workflow's settings from the Workflow Environment Variables panel. Alfred exports these settings as environment variables, and you can read them ad-hoc with the Config.Get*() methods, and save values back to Alfred with Config.Set(). Using Config.To() and Config.From(), you can "bind" your own structs to the settings in Alfred: And to save a struct's fields to the workflow's settings in Alfred: See the documentation for Config.To and Config.From for more information, and _examples/settings for a demo workflow based on the API. The Alfred struct provides methods for the rest of Alfred's AppleScript API. Amongst other things, you can use it to tell Alfred to open, to search for a query, or to browse/action files & directories. See documentation of the Alfred struct for more information. AwGo provides a basic, but useful, API for loading and saving data. In addition to reading/writing bytes and marshalling/unmarshalling to/from JSON, the API can auto-refresh expired cache data. See Cache and Session for the API documentation. Workflow has three caches tied to different directories: These all share the same API. The difference is in when the data go away. Data saved with Session are deleted after the user closes Alfred or starts using a different workflow. The Cache directory is in a system cache directory, so may be deleted by the system or "System Maintenance" tools. The Data directory lives with Alfred's application data and would not normally be deleted. Subpackage util provides several functions for running script files and snippets of AppleScript/JavaScript code. See util for documentation and examples. AwGo offers a simple API to start/stop background processes via Workflow's RunInBackground(), IsRunning() and Kill() methods. This is useful for running checks for updates and other jobs that hit the network or take a significant amount of time to complete, allowing you to keep your Script Filters extremely responsive. See _examples/update and _examples/workflows for demonstrations of this API.


Version published


<div align="center">
    <img src="" alt="AwGo Logo" title="AwGo Logo">

AwGo — A Go library for Alfred workflows

[![Build Status][ghaction-badge]][ghaction-link]
[![Go Report Card][goreport-badge]][goreport-link]
[![Coverage Status][coveralls-badge]][coveralls-link]

[![Build Status][azure-badge]][azure-link]
[![Build Status][travis-badge]][travis-link]
[![Codacy Quality][codacy-badge-quality]][codacy-link]
[![Codacy coverage][codacy-badge-coverage]][codacy-link]
[![Codecov coverage][codecov-badge]][codecov-link]

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

- [Features](#features)
- [Installation & usage](#installation--usage)
- [Documentation](#documentation)
- [Requirements](#requirements)
- [Development](#development)
- [Licensing & thanks](#licensing--thanks)


- Full support for Alfred 3 & 4
- Bi-directional interface to [workflow's config][config]
- Fluent API for generating [Script Filter JSON][feedback]
- [Fuzzy sorting/filtering][fuzzy]
- [Simple, powerful API][cache-api] for [caching/saving workflow data][cache]
- Keychain API to [securely store (and sync) sensitive data][keychain]
- Helpers to [easily run scripts and script code][scripts]
- Workflow [update API][update] with built-in support for [GitHub][update-github] & [Gitea][update-gitea]
- [Pre-configured logging][logging] for easier debugging, with a rotated log file
- [Catches panics, logs stack trace and shows user an error message][run]
- ["Magic" queries/actions][magic] for simplified development and user support
- macOS [system icons][icons]

Installation & usage

Install AwGo with:

go get -u

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.


package main

// Package is called aw
import ""

// 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

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

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

./program "$1"


Read the docs [on GoDoc][godoc].

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


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+)


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

Licensing & thanks

This library is released under the [MIT licence][licence]. It was built with
[neovim][neovim] and [GoLand by JetBrains][jetbrains].

The icon is based on the [Go Gopher][gopher] by [Renee French][renee].

[licence]: ./LICENCE




Last updated on 21 May 2020

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc