Package aw is a "plug-and-play" workflow development library/framework for Alfred 3 & 4
(https://www.alfredapp.com/). It requires Go 1.13 or later.
It provides everything you need to create a polished and blazing-fast Alfred
frontend for your project.
As of AwGo 0.26, all applicable features of Alfred 4.1 are supported.
The main features are:
AwGo is an opinionated framework that expects to be used in a certain way in
order to eliminate boilerplate. It *will* panic if not run in a valid,
minimally Alfred-like environment. At a minimum the following environment
variables should be set to meaningful values:
NOTE: AwGo is currently in development. The API *will* change and should
not be considered stable until v1.0. Until then, be sure to pin a version
using go modules or similar.
Be sure to also check out the _examples/ subdirectory, which contains
some simple, but complete, workflows that demonstrate the features
of AwGo and useful workflow idioms.
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.
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
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), use NewFromEnv() with a custom
A Workflow can be re-configured later using its Configure() method.
See the documentation for Option for more information on configuring a Workflow.
AwGo can check for and install new versions of your workflow.
Subpackage update provides an implementation of the Updater interface and
sources to load updates from GitHub or Gitea releases, or from the URL of
an Alfred `metadata.json` file.
See subpackage update and _examples/update.
AwGo can filter Script Filter feedback using a Sublime Text-like fuzzy
Workflow.Filter() sorts feedback Items against the provided query, removing
those that do not match.
See _examples/fuzzy for a basic demonstration, and _examples/bookmarks for a
demonstration of implementing fuzzy.Sortable on your own structs and customising
the fuzzy sort settings.
Fuzzy matching is done by package https://godoc.org/go.deanishe.net/fuzzy
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/info.plist with
Using Config.To() and Config.From(), you can "bind" your own structs to the
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, to browse/action files & directories, or to run External Triggers.
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 (almost) the same API. The difference is in when the data go
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
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.