Alfred Workflow #

A helper library in Dart for authors of workflows for Alfred 3 and 4.

This library is heavily inspired by the excellent Python 2 library deanishe/alfred-workflow.

In its current state it is very basic and only implements the Alfred Script Filter JSON API.

🚸 Usage #

🎉 Basic example #

void main(List<String> arguments) async {
  /// Instantiate an AlfredWorkflow
  final workflow = AlfredWorkflow();

  try {
    exitCode = 0;

    /// Define an ArgParser that uses -q/--query to listen to search queries
    final ArgParser parser = ArgParser()
      ..addOption('query', abbr: 'q', defaultsTo: '');

    /// Parse the args
    final ArgResults args = parser.parse(arguments);

    /// Sanitize the query string obtained from the args
    final String query = args['query'].replaceAll(RegExp(r'\s+'), ' ').trim();

    if (query.isEmpty) {
      /// In case of an empty query display a placeholder in the Alfred feedback
      workflow.addItem(
        const AlfredItem(
          title: 'Search for some particular stuff ...',
          icon: AlfredItemIcon(path: 'icon.png'),
        ),
      );
    } else {
      /// When there is a query do something fancy

      /// In this case we'll search Google with our query.
      final Uri url = Uri.https('www.google.com', '/search', {'q': query});

      /// Add an item to the Alfred feedback
      workflow.addItem(
        AlfredItem(
          title: 'Sorry I can\'t help you with that query.',
          subtitle: 'Shall I try and search Google?',
          arg: url.toString(),
          text: AlfredItemText(
            copy: url.toString(),
          ),
          quickLookUrl: url.toString(),
          icon: AlfredItemIcon(path: 'google.png'),
          valid: true,
        ),
      );
    }
  } catch (err) {
    /// Set exit code to a non-zero number
    exitCode = 1;

    /// In case of errors you can simply output the message in the Alfred feedback
    workflow.addItem(
      AlfredItem(title: err.toString()),
    );
  } finally {
    /// This will always print JSON to the stdout and send that to Alfred.
    workflow.run();
  }
}

To search for the string "hello" simply execute this on the commandline:

dart run example.dart --query 'hello'

Check out the basic example here.

⚡ Speed it up using caching #

The library uses stash_file to cache results in the form of AlfredItems. All you need to do to enable it is to define a cacheKey.

/// Define a cacheKey. In this case you can just use the query.
workflow.cacheKey = query;

/// Check if anything using that cacheKey is already in the cache.
/// This will automatically add the cached items to the Alfred feedback.
final AlfredItems? cachedItems = await workflow.getItems();

/// If noting was cached simply do as before
if (cachedItems == null) {
  final Uri url = Uri.https('www.google.com', '/search', {'q': query});

  /// This will now automatically add the AlfredItem to the cache.
  workflow.addItem(
    AlfredItem(
      title: 'Sorry I can\'t help you with that query.',
      subtitle: 'Shall I try and search Google?',
      arg: url.toString(),
      text: AlfredItemText(
        copy: url.toString(),
      ),
      quickLookUrl: url.toString(),
      icon: AlfredItemIcon(path: 'google.png'),
      valid: true,
    ),
  );
}

Check out the caching example here.

⬆️ Auto-Update your workflows via GitHub releases #

Setting up Auto-Updating will require that you provide your workflow's Github repository URL and version. Optionally you can set an interval how frequently the workflow should check for updates.

Once an update is found it's downloaded to the temp and opened.

final AlfredUpdater updater = AlfredUpdater(
  /// Declare your workflow's Github repository URL
  githubRepositoryUrl: Uri.parse('https://github.com/your/repo'),
  /// Declare your workflow's current working version
  currentVersion: '1.0.0',
  /// Optionally set an interval how frequently it should check for updates
  updateInterval: Duration(days: 7),
);

/// Check for updates
if (await updater.updateAvailable()) {
  /// Run the update
  await updater.update();
}

To update the workflow simply run this from the commandline:

dart run example.dart --update

Check out the auto-update example here.

🚀 Building the workflow for production #

Dart scripts can be easily compiled to standalone executables eliminating the need for any external prerequisites.

To compile the script above simply run this from the commandline:

dart compile exe example.dart --output example

You can then invoke the executable from the commandline:

./example --query 'hello'

🌱 A couple of my Alfred Workflows built using this library #

• alfred-flutter-docs
• alfred-react-docs
• alfred-vue-docs
• alfred-tailwindcss-docs
• alfred-django-docs
• alfred-flask-docs
• alfred-laravel-docs
• alfred-nova-docs
• alfred-cakephp-docs
• alfred-gitmoji