A command line interface that augments Alfred workflows.

Table of Contents

• Features
• Screencast
• Requirements
• Setup
• Usage
  • Command Line Interface (CLI)
  • Customization
  • Themes
  • Workflows
    • Alchemists
    • Dry RB
    • Rubocop
    • Ruby
      • Bytes
      • Encodings
      • Hex
      • HTTP Statuses
      • Links
      • Number
      • Repeat
      • System Errors
      • System Signals
      • Text
      • UUID
      • Version
    • Other
• Architecture
• Troubleshooting
• Development
• Tests
• Versioning
• Code of Conduct
• Contributions
• License
• History
• Credits

Features

• Adds Ruby support to Alfred.

• Supports building advanced Workflows for personal augmentation.

Screencast

Requirements

1. macOS

2. Bash

3. Alfred

4. Alfred Powerpack

5. Frum

6. Ruby

Setup

To install, run:

gem install pennyworth

When using the --git_hub CLI option, you’ll want to supply your GitHub login and Personal Access Token with at least read access via the following environment variables:

GITHUB_API_LOGIN=
GITHUB_API_TOKEN=

You can configure these environment variables via direnv if using the CLI or through the Alfred Workflow Environment.

⚠️ When using Alfred Workflow environment variables, please ensure you check the Don’t Export option for these variables so you don’t expose your credentials when exporting/sharing workflows with others.

Usage

Command Line Interface (CLI)

From the command line, type pennyworth to view usage:

USAGE:
  -c, --config ACTION                      Manage gem configuration. Actions: edit || view.
      --encodings                          Render Alfred encodings script filter.
      --git_hub                            Render Alfred GitHub repositories script filter.
  -h, --help                               Show this message.
      --http_statuses                      Render Alfred HTTP statuses script filter.
      --ruby_gems                          Render Alfred RubyGems script filter.
      --system_errors                      Render Alfred system errors script filter.
      --system_signals                     Render Alfred system signals script filter.
      --text CONTENT                       Render Alfred text script filter.
  -v, --version                            Show gem version.

GITHUB OPTIONS:
      --organization [HANDLE]              Set organization. Default: "".
      --user [HANDLE]                      Set user. Default: "".

RUBYGEMS OPTIONS:
      --owner [HANDLE]                     Set owner. Default: "".

The following demonstrates how to use Pennyworth from the CLI or within an Alfred Script Filter:

pennyworth --config edit
pennyworth --config view

pennyworth --encodings

pennyworth --git_hub --organization alchemists
pennyworth --git_hub --user bkuhlmann

pennyworth --http_statuses
pennyworth --ruby_gems --owner bkuhlmann
pennyworth --system_errors
pennyworth --system_signals

pennyworth --text demo
pennyworth --text "An Example"

While the command line options are nice, the real power comes from using Pennyworth in conjunction with Alfred Script Filters. Without having Alfred wired up to consume the CLI output, you’ll only get a JSON in your console. To explain better, continue reading or skip ahead to the Workflows section.

Customization

This gem can be configured via a global configuration:

~/.config/pennyworth/configuration.yml

It can also be configured via XDG environment variables.

The default configuration is as follows:

:alfred:
  :preferences:
:inflections:
  - "Bkuhlmann": "bkuhlmann"
  - "Dry Auto Inject": "Dry AutoInject"
  - "Dry Cli": "Dry CLI"
  - "Flacsmith": "FLACsmith"
  - "Git Plus": "Git+"
  - "Mac Os Config": "macOS Configuration"
  - "Mac Os": "MacOS"
  - "Prawn Plus": "Prawn+"
  - "Rubocop Ast": "Rubocop AST"
  - "Rubocop Md": "Rubocop Markdown"
  - "Rubocop Rspec": "Rubocop RSpec"
  - "Xdg": "XDG"
:git_hub:
  :api_url: "https://api.github.com"
  :organization:
  :user:
:http:
  :statuses:
    :url: "https://httpstatuses.com"
:ruby_gems:
  :api_url: "https://rubygems.org/api/v1"
  :owner:

Feel free to take this default configuration, modify, and save as your own custom configuration.yml.

Themes

The above is shared as the Alchemists Alfred Theme which can be installed directly.

Workflows

Not all workflows require Pennyworth to run properly. For the workflows that do require Pennyworth support, the following assumptions are made:

1. Your Dotfiles are configured to use Bash and load your environment appropriately. Bash is not a hard requirement, though. You can use any shell you are comfortable with as long as you teach Alfred to load your development environment before running the Alfred Workflow.

2. You have the latest version of Alfred, Ruby, and Pennyworth installed.

3. You are using a Ruby version manager, like Frum, which ensures Ruby is on your load path.

With the above requirements in mind, the following sections document how to download and install all Pennyworth workflows that are compatible with Alfred. Should you want to tweak any of these workflows, you’d only need to edit an existing workflow or build your own with these settings:

Before diving into each workflow, I want to highlight that the following capabilities are available to all workflows depending on what kind of item is currently selected within the Alfred UI:

• SHIFT or COMMAND + y will launch Quicklook for any URL based workflow.

• ENTER or COMMAND + c will copy selections to clipboard (depends on context, though).

• COMMAND + l will launch Large Type of current selection.

• ENTER Will either copy selection to clipboard or launch URL in default web browser.

Alchemists

The official Alchemists workflow for site navigation.

1. Download and double click to install.

2. Type ax to activate.

💡 Use ENTER to view site, CONTROL to view changes, OPTION to view source, or COMMAND to view issues.

Dry RB

A Dry RB workflow for navigating all of the Dry RB site.

1. Download and double click to install.

2. Type dry to activate.

💡 Use ENTER to visit site, CONTROL to view changes, OPTION to view source, or COMMAND to view issues.

Rubocop

A Rubocop workflow for quick access to documentation, learning about project changes, viewing source code, etc.

1. Download and double click to install.

2. Type cop to activate.

💡 Use ENTER to view site, CONTROL to view changes, OPTION to view source, or COMMAND to view issues.

Ruby

This workflow is feature packed and only requires a single download. Once downloaded, double click to install, and then continue reading to learn all of the capabilities this single workflow provides.

Bytes

This keyword allows you to generate random bytes.

Type bytes to activate and ENTER generate. You can supply an optional number for specific length.

Encodings

This keyword allows you to quickly search for various encodings and/or their associated aliases to use in your own code.

Type encodings to activate. Use ENTER to copy label or OPTION to copy associated aliases to clipboard.

Hex

This keyword allows you to generate a random hex string.

Type hex to activate and ENTER generate. You can supply an optional number for specific length.

HTTP Statuses

This keyword allows you to look up statuses by code with quick access to the associated symbol for use in your own code. Includes associated documentation for sharing or learning more. All HTTP statuses are sourced from Rack::Utils::HTTP_STATUS_CODES which is why Rack is a dependency of this gem and also why some codes might not be present like these unofficial codes.

Type https to activate. Use ENTER to copy symbol, CONTROL to copy code, OPTION to copy label, or COMMAND to view documentation.

Links

This keyword allows you to navigate to additional Ruby related information and resources.

Type rb plus SPACE to activate, then fuzzy type to filter the list to what you are looking for, and hit ENTER to visit the link in your default browser.

Number

This keyword allows you to generate a random number.

Type number to activate and ENTER generate. You can supply an optional number for specific length.

Repeat

This keyword allows you to generate a repeating sequence of the same character(s).

Type repeat to activate and ENTER generate. You must supply the character(s) you want to repeat followed by a number indicating how many times you want the character(s) to repeat.

System Errors

This keyword allows you to search low-level system errors. Depending on which operating system you are on, these errors will differ. Error IDs are provided for fuzzy searching since they are what you’ll most likely see in your stack dumps. The associated constant can be copied to clipboard for use in your Ruby code.

Type syserr to activate. Use ENTER to copy constant, CONTROL to copy ID, OPTION to copy description, or COMMAND to copy ID, name, and description.

System Signals

This keyword is for searching and acquiring the system signal you want to trap in your Ruby code.

Type signals to activate. Use ENTER to copy name, OPTION to copy ID, or COMMAND to copy ID and name.

Text

This keyword is for is for basic text manipulation. Supply a string, phrase, or sentence and let Pennyworth calculate all transformations and information you might need.

Type text to activate plus andy string or phrase to transform. Use ENTER to copy text to clipboard.

UUID

This keyword allows you to generate a random Universally Unique IDentifier (UUID).

Type uuid to activate and ENTER generate.

Version

This keyword allows you obtain Ruby version information.

Type version to activate and ENTER generate. Optionally, you can press OPTION when selected to answer the Ruby version used by Alfred since Alfred defaults to using whatever version is supplied by macOS.

Other

The following workflows don’t require Pennyworth support but are provided for convenience in case they are of interest/aid to your own productivity. Click each link to download and then double click to install:

• Acronyms - Expands acronyms into full explanations so you can think and type in terms of an acronym but appear as if you typed out the full definition each time.

• Alpine - Provides Alpine Linux resources.

• Applications - Launches development environment but can be tweaked for your preferences. Using Alfred in this manner ensures your machine boots or restarts quickly and gives you more control over what is launched.

• Browsers - Provides browser related utilities.

• Bundler - Provides quick access to Bundler related resources.

• Hanami - Provides Hanami resources.

• chi.li - Shortens URLs using chl.li.

• Docker - Provides Docker resources.

• macOS - Provides macOS utilities.

• Terraform - Provides Terraform resources.

• Text - Provides general text manipulation utilities beyond the Pennyworth powered text keyword (mentioned earlier).

Architecture

The following documents the workfow used to process all actions from Alfred.

Troubleshooting

• Psych 4.0.0 has a bug which prevents loading of YAML configurations that use symbols as keys. If you get caught by this, please upgrade to Psych 4.0.1 for the fix.

• When your Alfred Workflow yields no output, you might want to open the Alfred Debugger, rerun your workflow, and check for errors. You can also jump to the CLI and run Pennyworth directly.

• If you get GitHub authorization errors, make sure you have defined the appropriate credentials (mentioned earlier) for both within your shell where you are running Pennyworth or within the Alfred Workflow environment.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/pennyworth.git
cd pennyworth
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bundle exec rake

Versioning

Read Semantic Versioning for details. Briefly, it means:

• Major (X.y.z) - Incremented for any backwards incompatible public API changes.

• Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.

• Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

Code of Conduct

Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING for details.

License

Read LICENSE for details.

History

Read CHANGES for details.

Credits

Engineered by Brooke Kuhlmann.