awf

Contents

• awf — a CLI for managing Alfred workflows
  • Retrieving information about workflows
  • Locating workflows
  • Editing workflows
  • Installing and exporting workflows
  • Developing workflows
• Installation
  • Prerequisites
  • Installation from the npm registry
  • Manual installation
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

awf — a CLI for managing Alfred workflows

awf (Alfred Workflow) is an OS X CLI for managing and assisting in the development of workflows for command-line launcher Alfred - versions 3 and 2 are supported.

It comes with a broad range of features:

Note: Some features related to Alfred Preferences.app involve GUI scripting and therefore require that the application running awf - typically, Terminal.app - be granted access to accessibility features - you will be prompted for authorization on first use; for more information, see Apple's support article on the subject.

Retrieving information about workflows

• List all workflows or workflows matching a filter, optionally with selectable output fields.
  • awf list -s i net.same2u. # list matching workflows by bundle ID substring
• Print information about a given workflow.
  • awf info net.same2u.speak.awf

Locating workflows

• Locate a workflow's installation folder by its bundle ID.
  • awf which net.same2u.speak.awf # prints installation folder path
• Reveal a workflow's folder in Finder.
  • awf reveal net.same2u.speak.awf
• Trigger a keyword search for workflows in Alfred Preferences.
  • awf search speak

Editing workflows

• Change to a workflow's folder in Terminal.
  • awf cd net.same2u.speak.awf # opens a tab in a new window
• Open a workflow in Alfred Preferences for editing.
  • awf edit net.same2u.speak.awf
  • awf edit # from a workflow source folder

Installing and exporting workflows

• Install a (copy of a) workflow from a source folder.
  • awf install .
• Export a *.alfredworkflow archive from a source folder.
  • awf export . # exports to '*.alfredworkflow' in same folder by default

Developing workflows

Note:

• The purpose of the following features is to allow you to store workflows being developed in a separate location instead of directly among the installed workflows. A symlink to the dev location placed among the installed folders ensures that you can still use and develop the workflow from within Alfred and Alfred Preferences.
• These features move directories, create symlinks, and delete files. Care is taken not to accidentally overwrite or delete files, but use these features with caution and always create backups.

---

• Symlink a dev folder (source folder) into the folder of installed worklows or remove a dev folder's symlink.
  • awf link . # effective installation without moving the directory
  • awf unlink . # remove a symlink - effective uninstallation
• Move an existing, regular workflow to a dev folder in a different location and replace the original workflow folder with a symlink to the dev folder.
  • awf todev net.same2u.speak . # move to current folder and perform 'awf link'
• Conversely, move a dev folder back to the folder of installed workflows as a regularly installed workflow.
  • awf fromdev . # -k keeps the source folder
• Manage workflow version numbers via file version.
  • awf version patch # bumps the patch component of the workflow's version number

The Usage chapter contains the full manual.

Installation

Prerequisites

• macOS (OS X)
• Alfred version 3 or 2 with its paid Power Pack add-on.

Installation from the npm registry

^{Note: Even if you don't use Node.js itself: its package manager, npm, works across platforms and is easy to install; try
curl -L http://git.io/n-install | bash}

With Node.js installed, install the package as follows:

[sudo] npm install -g awf

Note:

• Whether you need sudo depends on how you installed Node.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
• The -g ensures global installation and is needed to put awf in your system's $PATH.

Manual installation

• Download the CLI as awf.
• Make it executable with chmod +x awf.
• Move it or symlink it to a folder in your $PATH, such as /usr/local/bin.

Usage

awf currently does not have a man page, but its manual is accessible through the help sub-command:

• awf help (or awf -h) gives a concise overview of all sub-commands.
• awf help all additionally prints detailed descriptions of all sub-commands.
• awf help <sub-command> prints the detailed description of the specified sub-command; e.g., awf help list

$ awf --help

SYNOPSIS
  awf list|ls [-b] [-o fieldIdChars] [[-s fieldIdChars] [-x|-r] searchTerm]
    Lists installed workflows, optionally with custom output and filtering.
  awf search          [searchTerm]
    Searches for workflows in the Alfred Preferences application.

  awf info [-b] [-o fieldIdChars] [wfFolderOrBundleID]
    Prints a workflow's metadata, optionally with selectable output fields.
  awf id              [wfFolder]
    Prints the bundle ID of a workflow.
  awf which [-l|-P] [-R]          [wfDevFolderOrBundleID]
    Prints the full path to an installed workflow's folder.    
  awf reveal [-P]     [wfDevFolderOrBundleID | '/']
    Reveals an installed workflow's folder in Finder.
    '/' reveals the root of Alfred's workflow folders.

  awf cd [-P]         [wfFolderOrBundleID | '/']
    Changes to an installed workflow's folder in a new Terminal window.
    '/' changes to the root of Alfred's workflow folders.
  awf edit            [wfFolderOrBundleID]
    Opens a workflow for editing in the Alfred Preferences application.

  awf install         [wfDevFolder]
    Installs a workflow from a dev folder.
  awf export  [-R]    [wfFolderOrBundleID [outFolder]]
    Exports a workflow to an *.alfredworkflow ZIP archive.

  awf link|ln [-f]    [wfDevFolder [symlinkName]]
    Symlinks a dev workflow into the folder of installed workflows.
  awf unlink|unln     [wfFolderOrBundleID]
    Removes a symlink to a dev workflow from the folder of installed ones.
  awf prune
    Removes dead symlinks from the folder of installed workflows.
  awf todev [-R]      [wfInstalledFolderOrBundleID [wfDevFolder]]
    Converts an installed workflow to a dev workflow.
  awf fromdev [-k]    [wfDevFolder]
    Converts a dev workflow to a regular installed workflow.
  awf version [-f] [newVersion|'major|'minor'|'patch' [wfFolderOrBundleId]]
    Prints or assigns a workflow's version number.

  awf help [command | 'all']  # or: awf command -h
    Prints help information.

DESCRIPTION
  Performs various operations related to Alfred workflows.
  (To learn about Alfred, go to http://alfredapp.com)
  Supports Alfred 3 and Alfred 2; if both are installed, pass -2 as the very
  first argument to target Alfred 2.

  To get help for a specific command, use `awf help <command>`
  or `awf <command> -h`.
  
  WFDEVFOLDER is a folder path containing an Alfred workflow
   *dev* (development) project, in a *separate location* from and
   and typically symlinked into the folder hosting all installed
   workflows.
  
  WFINSTALLEDFOLDER is a path to a workflow folder among the
   *installed* workflows.
  
  WFFOLDER can be either a dev or an installed workflow folder.
  
  Generally, not specifying a folder (or bundle ID) defaults to the current
  folder.

  In commands where a bundle ID can be specified to target a workflow, only
  *installed* workflows are searched for said bundle ID.

  For license information and more, visit https://github.com/mklement0/awf

License

Copyright (c) 2015-2016 Michael Klement [e-mail] (http://same2u.net), released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies

• doctoc (D)
• json (D)
• replace (D)
• semver (D)
• urchin (D)

Changelog

• v0.3.0 (2016-09-15):

  • [enhancement] Alfred 3 is now supported as well. If both Alfred 2 and Alfred 3 are installed, Alfred 2 can be targeted by passing -2 as the very first argument.

• v0.2.4 (2015-11-07):

  • [fix] edit sub-command now processes its operand correctly and now fails in case a dev folder is specified that isn't currently symlinked as an installed folder.
  • [dev] Internal optimizations and stability improvements.

• v0.2.3 (2015-11-07):

  • [doc] README.md: Removed spurious 10.10 requirement; copy-editing.

• v0.2.2 (2015-11-07):

  • [doc] Typo fixed.
  • [dev] Automatic TOC generation for README.md disabled for now, because doctoc doesn't parse the "Usage" chapter correctly.

• v0.2.1 (2015-11-07):

  • [doc] TOC added to README.md

• v0.2.0 (2015-11-07):

  • First release.
  • [change] afw version now expects the version number/increments specifier before the target-folder operand; '' is now needed to explicitly ask to get the current version when also specifying a target-folder operand.
  • [change] afw export now uses a workflow's bundle ID as the filename root by default.
  • [change] Options may now be intermingled with operands (though the sub-command must still be the very first argument).
  • [fix] Various small fixes.

• v0.1.0-3 (2015-10-28):

  • [fix] awf export should now work as advertised (support for output-folder argument, resolution of relative paths).

• v0.1.0-2 (2015-10-28):

  • [fix] Using . as the target dev folder for awf link is now handled correctly.

• v0.1.0-1 (2015-10-28):

  • [fix] Using . as the target dev folder for awf todev is now handled correctly.
  • [enhancement] If the target dev folder for awf todev is found to be located inside a package project (specifically, if ../package.json exists), it is now the parent folder's name that is used to form the symlink name, as it is assumed to be project-specific, whereas the subfolder hosting the workflow source code may not.

• v0.1.0-0 (2015-10-28):

  • [doc] CLI help improved.