Gallium is a general purpose fuzzy-finder and thing-doer inspired by Quicksilver, fzf, choose, and Unix. You can quickly fuzzy search thousands of items, select one, and act on it. The items, and the actions, are provided by you.

Adding an item to Gallium's library is as simple as editing a config file. You can specify the type of item, an optional icon, and a command Gallium can execute to load those items into Gallium. The command is any Unix executable, like a shell script or other CLI tool. Here's an example of adding a config to Gallium's config.toml that defines a Bookmark item type.

        [[sources]]
        type = { name = "bookmark", icon = "bookmark.fill" }
        command = "/Users/matt/.config/gallium/load-bookmarks.sh"
      

The command used to load items can be anything runnable from the command line, it just needs to be able to spit out CSV formatted text to STDOUT. For example, here's a simple script that just echoes a few hard coded bookmarks.

        #!/usr/bin/env sh
        echo "bookmark,Kagi,https://kagi.com"
        echo "bookmark,Hacker News,https://news.ycombinator.com"
        echo "bookmark,Gallium,https://gallium.run"
      

When you launch Gallium you'll see they're searchable.

Searching isn't very useful without actions, so let's define an action for bookmarks.

      [[actions]]
      forType = "bookmark"
      name = "Open in browser"
      icon = "link.circle"
      command = "/Users/matt/.config/gallium/open-bookmark.sh"
      

Now we'll see an "Open in browser" action when we select an item in Gallium of type "bookmark". When we run the action, the bookmark item we've selected will be passed into our action via STDIN.

Here's the contents of `open-bookmark.sh`. You can see it just reads the bookmark from STDIN and then uses the built-in `open` command in macOS to open the URL.

      #!/usr/bin/env sh

      read bookmark
      open "$bookmark"
      

Here's an example that will turn Gallium into an app launcher. First, we register a new type in our config.

        [[sources]]
        type = { name = "application", icon = "app.fill" }
        command = "/Users/matt/.config/gallium/load-apps.sh"
        refreshInterval = { interval = 1, unit = "minutes" }
      

Here's we're setting a refresh interval so that new apps will be detected every 60 seconds. That just means `load-apps.sh` will be re-run every minute.

`load-apps.sh` just uses `find` to search for apps in typical locations and prints them out to STDOUT in CSV format. We use `awk` for that here.

        #!/usr/bin/env sh

        find /Applications \
             /Applications/Utilities \
             /System/Applications \
             /System/Applications/Utilities \
             -maxdepth 1 -name '*.app' | \
        awk -F'/' '{
              # Get the app file name
              app_name = $(NF);
              # Remove .app from the name
              sub(".app", "", app_name);
              # Print in CSV format, i.e.
              # "application, App Name, /Applications/App Name.app"
              print "application," app_name "," $0
          }'
      

And we can register an "open" command that also uses the `open` command built into macOS.

        [[actions]]
        forType = "application"
        name = "Launch"
        icon = "arrow.up.forward.square"
        command = "/Users/matt/.config/gallium/open-application.sh"
      

        #!/usr/bin/env sh

        read application
        open -a "$application"