Changes to Hook's AppleScript API coming in Hook 2.0

This is a pre-announcement regarding the upcoming Hook 2.0 AppleScript.

Following experience with and feedback on Hook’s AppleScript dictionary we are making some improvements to Hook’s AppleScript dictionary. You may recall that we introduced the dictionary in the spring. Our new AppleScript dictionary more directly provides an API to generally access Hook’s data, and allows users to flexibly use various standard AppleScript idioms, syntax and design patterns to interact with it. (I.e., it align with AppleScript conventions.) It introduces some new dictionary terms. The implementation will also be faster.

We know some of you are using tools that depend on Hook’s automation, such as

Rest assured that the first two will be updated by us and released with 2.0. And Brett Terpstra (@ttscoff) will update his Hook CLI - GitHub.

changes to bookmark

the bookmark object has been changed from a record to a class. It has 4 properties:

  • address is the item’s URL, and serves as the class’s ID

  • name is exactly what it says on the tin

  • posixPath is a generated property based on the item’s address. If the item is a file which is present and available to user, posixPath is the (unencoded) path of that file

  • hooked bookmarks is a list of the bookmarks which are linked to this bookmarked item.

Since bookmarks are a class, the bookmark from URL command has been replaced with existing standard AppleScript syntax for creating or getting a class object. Likewise, the all bookmarks command is redundant and has been eliminated, since bookmarks is an element of the Hook Application object.

Some examples:

  1. To get a list of every bookmark in Hook: bookmarks or every bookmark
  2. To get a random bookmark: some bookmark
  3. To quickly filter: every bookmark whose name contains "bread" and address begins with "hook://email"
  4. To get a bookmark with a given URL: get bookmark id <URL>
  5. To create a new bookmark: make bookmark with data ""
    or make bookmark with properties {address:"", name:"Hook"}

Note the difference between #4 and #5. bookmark id <URL> only works if the bookmark already exists in Hook. If there is any uncertainty, it is safer to use #4.

changes to other commands

  • bookmarks hooked to command has been deprecated, replaced with the hooked bookmarks property
  • has hooked bookmarks for URL has been deprecated, since it is now easy to do exists hooked bookmarks of bookmark id <URL>
  • hook together and remove hook have been renamed to hook and unhook

Other commands unchanged

The other commands are all unchanged, except that they have been updated to return or operate on a bookmark class object, instead of a record.

As explained above, the deprecated commands will remain in place alongside the new syntax until version 2.2.

The dictionary

The dictionary file will be be available from Hook’s AppleScript page. Like this post if you would like us to share a copy sooner rather than later.

Hook 2.0 release date

We are not ready to publish a specific release date for Hook 2.0. However, it’s coming along very well. We’ve put more into it than we had expected. It’s currently tracking for late Sept - early Oct. But no promise of a specific date.

Per Hook’s license terms, updates are free for a year; also available to anyone who has a valid Updates license. Updates licenses last a year.

over to you

We welcome comments and questions as always.


I’ve updated the CLI on GitHub, but am holding off on pushing the gem until the 2.0 release (so users don’t end up with a non-functioning version).

Anyone who wants to use the CLI with a pre-release version of Hook 2.0 can download the source from GitHub. You’ll need bundler. Just run bundle install and then rake package and (if all goes well) you’ll get a gem file in /pkg that you can then install with gem install pkg/hookapp-2.0.0.gem.


Super! Thanks Brett!

For all, Hook’s AppleScript Dictionary – Hook page now contains a link to a compressed version of the .sdef ( AppleScript ) file. It’s for Hook 2.0 build 3636 which is in private beta. Enjoy :blush: .

We might soon expand the private beta. Please like this topic if you’d like to join the beta. Beta customers may be asked to answer a brief survey about the app.


The latest version of the gem with Hook 2.0 compatibility is now available, use gem install hookapp (or gem update hookapp if already installed).


Hi Luc,
The Alfred scripts around the Hook workflow broke with the newest 2.0 update - would an Alfred workflow for Hook be made available soon?

oops! we had uploaded the workflows but not changed the link to them. They are now both available from Alfred Workflows for Hook. Thanks for letting us know, @pralayb.

Thanks @LucB

Can you clarify the order in which the bookmarks are presented within Alfred? It is not alphabetical and I do not think it is chronological based on when it was created or modified.

I’ll have to ask someone here to dig into it. It should be the same result as what you’d get from calling the corresponding AppleScript. The script uses the same API as exposed in Hook’s AppleScript dictionary.

1 Like