node package manager



Alfred workflow bindings for NodeJS. Inspired by Alfy and alfred-workflow-nodejs.

Build Status Open Issues


  • Written in Flow using Babel.
  • Fuzzy search/filter your data using Fuse.js.
  • Fetch (JSON) from REST API's using Got.
  • Group multiple actions in one file.
  • Update notifications (for both NPM and Packal workflows).




Hugo is available as NPM package and can be installed with npm.

$ npm install --save alfred-hugo


In your project simply require/import Hugo and off you go 😎

var Hugo = require('alfred-hugo');
// or 
import Hugo from 'alfred-hugo';

When you decide to write your Alfred workflow in Flow, you'll benefit from static type checking. Flow will automatically find and use the Flow annotations in the Hugo package and any other packages written in Flow. Please see the Flow documentation for more info about declarations.


// @flow 
var Hugo = require('alfred-hugo');
var myOptions = false;
Hugo.options(myOptions); // Will cause an error as Hugo.options expects an Object 

​If you feel like writing your code in plain Javascript … that's fine too 😄 You can still use all the wonderful features of Hugo.


Please see the examples directory for, well ... examples.




Type: boolean

Default: true

Enable/disable checking for updates.


Type: string

Default: packal

Possible values: packal npm

Check Packal or NPM for updates of the workflow. If the package can't be found on NPM then Packal will be checked as fallback.


Type: number Duration

Default: 1 day (86400 seconds)

Interval to check for updates in seconds or as Duration.


Type: boolean

Default: true

Display a notification bubble when a workflow update is available. The notification bubble will only display once every updateInterval.

Clicking the notification won't do anything at this moment but node-notifier has extensive support for user interaction. Pull requests are welcome!


Type: boolean

Default: true

Display an update item at the bottom of the list when an update is available.

When the item is activated, it will set a variable named task ({var:task} in Alfred) with the value wfUpdate. The argument is set to the URL where the update can be found, either on Packal or NPM depending on updateSource. You can link the output to an Open URL action so a browser opens when the user selects the update item.

Opening a browser for updates


Type: boolean

Default: true

Use the OS temp directory for your workflow cache when true, otherwise use the directory set by Alfred in thealfred_workflow_cache environment variable. It's recommended to leave this set at true unless you want your cache to survive reboots and clean it up yourself every once in a while.



Type: Object

Collection of Alfred metadata that is available to the script through environment variables. See the alfred documentation for more info:

When you use a custom Alfred theme, the themeFile property will be set to the path of the theme file (which is a JSON file). Also see Hugo.alfredTheme.

    version: process.env.alfred_version,
    theme: process.env.alfred_theme,
    themeFile: '',
    themeBackground: process.env.alfred_theme_background,
    themeSelectionBackground: process.env.alfred_theme_selection_background,
    themeSubtext: parseFloat(process.env.alfred_theme_subtext),
    preferences: process.env.alfred_preferences,
    preferencesLocalHash: process.env.alfred_preferences_localhash,
    debug: process.env.alfred_debug === '1'

Also see: Hugo.workflowMeta


Type: Object

When a custom Alfred theme is used, this will return the contents of the theme file. Usefull if you need to render icons on-the-fly and want to know the background colour.


Type: cache-conf

Simple cache config handling for your app or module


Type: conf

Simple config handling for your app or module


Type: string

Hugo.input contains the user input (first argument to the script) and can be used to filter your items.

Even if you use this inside an action method, it will still return the correct user input, though I recommend using the provided query argument as can be seen in the examples.


Type: number

Number of Alfred items in the current output buffer.


Type: Object

Current output buffer (read-only).


Type: Object

Collection of workflow metadata that is available to the script through environment variables. See the alfred documentation for more info:

    name: process.env.alfred_workflow_name,
    version: process.env.alfred_workflow_version,
    uid: process.env.alfred_workflow_uid,
    bundleId: process.env.alfred_workflow_bundleid,
    data: process.env.alfred_workflow_data,
    cache: process.env.alfred_workflow_cache,
    icon: path.join(process.cwd(), 'icon.png')




Type: Object

Item to add to the list of items which will be displayed. The only property that is required is title, all the others are optional. See the Alfred documentation for all the supported properties.

Item variables

One thing that is simplified in Hugo (and quite undocumented in Alfred) is the way to add variables to items using the arg property. Instead of supplying a string you can supply an Object to assign variables to an item instead of globally. Now when an item is activated it will set those environment variables during this session so you can use them throughout your Alfred workflow in other actions.

    title: 'My item',
    arg: {
        arg: 'my argument',
        variables: {
            foo: 'bar',
            bleep: 'bloop'



Type: Array

Add multiple items to the list of items which will be displayed. See Hugo.addItem for more info.

Hugo.addVariable(key, value)


Type: string


Type: string Object


Variables can be passed out of the script filter within a variables object. This is useful for two things. Firstly, these variables will be passed out of the script filter's outputs when actioning a result. Secondly, any variables passed out of a script will be passed back in as environment variables when the script is run within the same session. This can be used for very simply managing state between runs as the user types input or when the script is set to re-run after an interval.

    "variables": {
        "foo": "bar"
    "items": [

See the Alfred documentation for more info about session variables.



Type: Object

Hugo.action(keyword, callback)


Type: string

Action name (myaction in the example below),


Type: function

Callback to execute when the keyword matches the first argument. The callback takes one argument, the user input (myquery in the example below).

/usr/local/bin/node index.js myaction "myquery"

Hugo.cacheFile(filepath, cacheName)

Processing/parsing files often takes time and is only needed when the file has changed. You can cache the results for a period of time, but you'll be left with an outdated cache when the file changes.

This method makes caching the processed results a lot easier by checking whether a file has changed. If it hasn't changed, get() will return the cached value. If no cached result is found or the file has changed, the change event will be emitted with a reference to the cache store, file contents and SHA-1 hash so you can process your file and store the results in the cache store.

* It's recommended to have the useTmpCache option set to true to prevent the cache from piling up as it isn't cleaned from time to time, unlike your OS temporary folder (for example /tmp) which is cleared after a reboot.


Type: string

Absolute path to the file that you like to process and check for changes.


Type: string

Cache name, this will be the name of the directory where the cached results are stored. It's possible but not recommended to share one cache name with other cacheFile instances.

Check out file-cache.js.flow and the example to see how to implement it.


Checks for workflow package updates on either NPM or Packal when enabled. No need to call this method manually, updates will be checked automagically ​✨​


Empties the workflow cache directory but doesn't remove the directory itself.

Call Hugo.clearCacheSync() if you need it synchronously.

Hugo.filterItems(query, options)

Fuzzy filter the output buffer by search query using Fuse.js. Add items to the output buffer first and then call filterItems to remove the items that do not match the search query. This method alters the output buffer directly.


Type: string

Search query


Type: Object

Fuse.js options, please see the documentation for available options.



Type: Object

Set Hugo options, see below for available options and their defaults:

    checkUpdates: true,
    updateSource: 'packal',
    updateInterval: moment.duration(1, 'days'), // 86.400 seconds 
    updateNotification: true,
    updateItem: true

Hugo.matches(candidates, query, options)

Filter the list of candidates by search query using Fuse.js. This will return the filtered candidates list.


Type: Array<Object>

List of candidates to filter. This may be any object, not specifically an Alfred item.


Type: string

Search query


Type: Object

Fuse.js options, please see the documentation for available options.


Scripts can be set to re-run automatically after an interval using the 'rerun' key with a value of 0.1 to 5.0 seconds. The script will only be re-run if the script filter is still active and the user hasn't changed the state of the filter by typing and triggering a re-run.


Type: number

Checks for updates (if enabled) and flushes the output buffer to the console so Alfred can display the items.

Hugo.fetch(url, options, cacheAge)

Helper method to fetch an URL with got and optionally cache the result. Useful when working with REST API's.


Type: string


Type: Object

See the got documentation for all available options.


Type: number null

Number of seconds to cache the result.

Publishing your workflow to NPM

To publish your workflow to NPM, use alfred-link.

Add the alfred-link command as postinstall script of your Alfred package and add alfred-unlink as preuninstall script to clean up the resources when the workflow gets uninstalled.

  "name": "alfred-unicorn",
  "scripts": {
    "postinstall": "alfred-link",
    "preuninstall": "alfred-unlink"

You can now install the alfred-unicorn package like this

$ npm install -g alfred-unicorn

This will update info.plist with the information from package.json and creates a unicorn symlink inside the Alfred workflows directory that points to the location of the alfred-unicorn module.

Workflows using Hugo

List of Alfred workflows using Hugo.

  • alfred-atom - Alfred workflow to browse and open Atom projects

Feel free to submit your own by opening an issue or submitting a pull request.


See CONTRIBUTING for more info about how to contribute.




BSD-2-Clause license, see LICENSE.