Hook CLI

A command line tool for Hook.app on macOS.

Hook is a great productivity tool for macOS that allows you to create links between your files, emails, websites, and everything in your digital life, no matter where each item exists. For people who spend a lot of time in Terminal, it only makes sense we should have access to Hook’s power from the command line.

For full documentation, visit the GitHub repository.


To install, just run gem install hookapp.

If you’re on a stock Ruby install (i.e. have never installed rvm or rbenv), use gem install --user-install hookapp.

If you run into errors, you may need sudo and your system password: sudo gem install hookapp.


Run hook help for usage:

    hook - CLI interface for Hook.app (macOS)

    hook [global options] command [command options] [arguments...]


    --help    - Show this message
    --version - Display the program version

    clip, cp   - Copy Hook URL for file/url to clipboard
    clone      - Clone all hooks from one file or url onto another
    from       - Get a Hook URL for the frontmost window of an app
    help       - Shows a list of commands or help for one command
    link, ln   - Create bidirectional hooks between two or more files/urls
    list, ls   - List hooks on a file or url
    open, gui  - Open the specified file or url in Hook GUI
    remove, rm - Remove a hook between two files/urls
    select     - Select from hooks on a file/url and open in default application

Run hook help COMMAND on any of the commands for more details.


Creating hooks

The link command always creates bidirectional hooks. Give it two or more files or urls and it will create links between them. By default it links all files to the last file in the list. Add the --all flag to link all files to every other file in the list. This can be abbreviated as hook ln -a file1.md file2.pdf "https://brettterpstra.com".

Similar to the way you would use the GUI, you can use hook clip file1.md to copy a Hook URL to the clipboard, and then use hook ln -p file2.pdf to create a link from the clipboard to file2.pdf.

You can also clone all of the links on one file to another, great for adding a new file to a group that’s fully crosslinked. Just use hook clone file1.md file2.pdf.

Listing hooks

Use the list (aliased as ls) command to list all attached hooks for a file. With no output format specified, ls will show the paths to all hooks, or the hook url if the hook doesn’t have a file path (e.g. a URL). You can specify an output format using --output_format (abbreviated as -o) with one of “markdown”, “hooks”, “paths”, or “verbose”. Formats can be abbreviated to their first letter, so to display a Markdown list of all hooked files, use hook ls -o m file1.md.

Removing hooks

Use hook remove file1.md file2.pdf to remove the bidirectional link between file1.md and file2.pdf. Add the --all flag (abbr. -a) with one or more files to remove ALL the hooks on them. This option requires confirmation.

Super nerdy scripting trick

The --output_format=paths option (abbr. -o p) combined with the --files_only flag (abbr. -f) will list just the paths and only include hooks that have file paths (i.e. exclude web, email, and other URLs). This can be combined with --null to output the list using a NULL separator, perfect for use with xargs or other command line tools.

Acting on hooks

You can open a hooked file or URL by running hook select file1.md. This will display a menu of all the hooks on file1.md, and entering the number of a selection will open that file in its default application.

You can also open a file in the Hook GUI using hook open file1.md.


Click to expand


  • Change fzf preview to Markdown listing


  • Fix permissions issues when installed using sudo


  • Fix fzf integration across platforms


  • Bug fixes
  • New tests


  • Incorporate fzf for selecting and filtering hooks
  • Improve documentation
  • Add scripts command to output completion scripts for various shells7
  • If no search is provided to hook find, list all hooks
  • If no file is provided to hook ls, list all hooks


  • Revamped to use Hook 2.0 AppleScript syntax
  • Added find command to search bookmarks


  • Fix missing variable in clipboard functions
  • Mv cp alias to mean clip instead of clone


  • hook from APP_NAME command
  • General code cleanup


  • Fix “conversion of nil into string” error


  • Fix to handle all url types, not just hook: and http:

Speaking of Hook CLI…

Related Projects