Alfred Client | Alchemists

Alfred Client

In the past, I’ve written about Alfred being a powerful augmenter of productivity. Alfred Snippets is one example and the Pennyworth gem is another. The Pennyworth gem, in particular, is my favorite way to supercharge Alfred because Pennyworth provides Ruby workflow firepower that would otherwise be missing.

In this article, I want to expand upon Alfred Workflow capabilities — documented via the Pennyworth gem — by focusing on how to use Alfred as a native client to your remote service. All you need is a JSON API that Alfred can consume which turns Alfred into a native client interface with minimal effort.

Table of Contents

Requirements
Demonstration
Implementation
- Workflow
- API
Conclusion

Requirements

Before getting started, let’s ensure your environment is properly configured so you can experiment, in real-time, as you read through this article. Here’s what you need:

Alfred - Free. 5.0.0 or higher is strongly recommended.
Powerpack - Paid. Necessary to unlock and use workflows.
Alchemists Workflow - Free. This’ll allow you to browse this site using Alfred only.

Demonstration

With the Alchemists Workflow installed, you’ll be able to immediately use Alfred as a native client for interacting with this site. The following demonstrates usage so you can experiment locally:

Notice, in the above videos, you can navigate the site using Alfred. Hitting ENTER on a selected item will immediately load the resource in your default browser for further viewing. Granted, you could browse the web site directly but now you can do this using Alfred with only a few keystrokes! Even better — as shown in the articles demonstration above — you can fuzzy filter with search criteria to narrow the results further. 🚀

Next, let’s unwrap how this functionality is made possible.

Implementation

When you use the COMMAND + SPACE keyboard shortcut to launch Alfred and type aa (example) to trigger the Alchemists Articles Script Filter, you are making an API request which answers back a JSON response for display within the Alfred UI. The following will walk you through the specifics of this flow.

Workflow

A visual is probably best to start with, so here’s a screenshot of the Alchemists Workflow:

I’ve highlighted and numbered each step in the workflow with blue counters which breaks down as follows:

Script Filter - Delegates to Bash to run a curl command. I’ll explain this more in a moment.
Conditional - Checks if a URL is answered back and opens the URL or issues an error notification.
Open URL Action or Post Notification Output - As mentioned in Step 2, a URL will be opened in your default browser or an error notification will be displayed.

Out of all steps, Step 1 is the most interesting because of the delegation to the Bash script. For articles, the script filter code looks like this:

curl "https://alchemists.io/api/alfred/articles.json" \
     --header "Accept: application/json" \
     --compressed

The above is making a HTTPS GET request to the Articles API which answers back a decompressed JSON response and is then filtered by Alfred to render results you can fuzzy filter further.

Now that you understand the workflow, at a high level, let’s study the API because the API is what makes all of this come together.

API

The JSON API adheres to Alfred’s Script Filter JSON Format (mentioned above). Using my Articles API as an example, here’s a code snippet for illustration:

{
  "items": [
    {
      "title": "How To Keep Your Best Programmers",
      "subtitle": "Book notes on engaging with and retaining engineering talent.",
      "arg": "http://localhost:3030/articles/how_to_keep_your_best_programmers",
      "quicklookurl": "http://localhost:3030/articles/how_to_keep_your_best_programmers",
      "mods": {
        "alt": {
          "subtitle": "By: Brooke Kuhlmann. Tags: Literature and Culture. Published: 2022-06-15. Updated: 2022-06-23.",
          "arg": "http://localhost:3030/articles/how_to_keep_your_best_programmers"
        }
      },
      "text": {
        "copy": "http://localhost:3030/articles/how_to_keep_your_best_programmers",
        "largetype": "How To Keep Your Best Programmers"
      }
    }
  ]
)

You can read the linked documentation to learn about the keys used but I want to highlight a few features of this design:

Quick Look URL: Triggered via CONTROL + y. Will preview the URL without leaving your Alfred results.
Modifications: Triggered via CONTROL, OPTION, or COMMAND. In this example, only the OPTION modifier is implemented but if you were to acquire project results then all modifiers would be implemented. Using all, some, or no modifiers depends on your use case. In my case, I’m either displaying additional metadata or providing alternative URLs to link to.
Text (copy): Triggered via COMMAND + c. Will copy the value (URL) to the clipboard. Handy for acquiring links without loading the page.
Text (large type): Triggered via COMMAND + l and displays the value (label) in large text across your screen. Handy for presentation purposes.

Conclusion

One motivation of this site is to always be a resource for others to benefit from. By providing Alfred support, the needle moves further in that direction. Maybe this’ll inspire you to something similar. If so, I’d like to know. Granted, not everyone is a macOS user but for those who are — and are Alfred fans — enjoy!