Script Filters

Script filters allow external commands to provide dynamic results in the launcher using a subset of the Alfred Script Filter JSON format.

Note

Script filters are only available in native mode. They are not available when using Fuzzel mode.

Overview

Script filters execute external commands when a keyword is typed, displaying dynamic results based on the command’s JSON output. This enables integration with APIs, databases, custom scripts, and more.

Configuration

Configure script filters in your raffi.yaml:

addons:
  script_filters:
    - name: "Timezones"
      keyword: "tz"
      command: "batz"
      args: ["-j"]
      icon: "clock"

    - name: "Bookmarks"
      keyword: "bm"
      command: "my-bookmark-script"
      args: ["-j"]
      action: "echo -n {value}|wl-copy"
      secondary_action: "xdg-open {value}"

Configuration Fields

name string (required)

Display name shown during loading

keyword string (required)

Text that activates the script filter

command string (required)

Executable to run

args array

Arguments passed before the query

icon string

Fallback icon name for results without their own icon

action string (default: copy)

Action on Enter. Options:

• "copy": Copy to clipboard
• "insert": Type into focused app via wtype/ydotool
• Command template with {value} placeholder (executed via sh -c)

secondary_action string

Action on Ctrl+Enter. Accepts same values as action. If omitted, Ctrl+Enter behaves same as Enter.

JSON Format

Script filters must output JSON matching this structure (subset of Alfred’s format):

{
  "items": [
    {
      "title": "New York",
      "subtitle": "EST (UTC-5) — 14:30",
      "arg": "America/New_York",
      "icon": { "path": "/usr/share/icons/clock.png" }
    },
    {
      "title": "London",
      "subtitle": "GMT (UTC+0) — 19:30",
      "arg": "Europe/London"
    }
  ]
}

JSON Fields

title string (required)

Main text displayed for the item

subtitle string

Secondary text shown below the title

arg string

Value copied to clipboard (falls back to title if omitted)

icon.path string

Absolute path to a PNG or SVG icon

How It Works

1. Type Keyword

   User types the configured keyword (e.g., tz)

2. Execute Command

   Script is executed with remaining input as final argument:

   batz -j "New York"

3. Parse JSON

   Raffi parses the JSON output from stdout

4. Display Results

   Items are displayed in the launcher

5. Handle Selection

   On Enter, the item’s arg value (or title) is used with the configured action

Actions

Default Action (Copy)

By default, selecting an item copies its value to the clipboard:

script_filters:
  - name: "Timezones"
    keyword: "tz"
    command: "batz"
    # Default action is "copy"

Custom Actions

Define custom actions using command templates:

Copy to Clipboard

action: "echo -n {value}|wl-copy"

Open in Browser

action: "xdg-open {value}"

Type into App

action: "insert"

Custom Command

action: "my-command --input {value}"

Primary and Secondary Actions

script_filters:
  - name: "Bookmarks"
    keyword: "bm"
    command: "bookmark-script"
    action: "echo -n {value}|wl-copy"  # Enter: Copy URL
    secondary_action: "xdg-open {value}"  # Ctrl+Enter: Open URL

Primary (Enter)

Copies bookmark URL to clipboard

Secondary (Ctrl+Enter)

Opens bookmark URL in browser

ANSI Color Support

The title and subtitle fields support ANSI color codes for colored text:

{
  "items": [
    {
      "title": "\u001b[32mSuccess\u001b[0m",
      "subtitle": "\u001b[90mCompleted at 14:30\u001b[0m"
    }
  ]
}

Tip

The pr.py script from alfred-pr-workflow uses colors to display pull request states.

Examples

Timezone Converter

Using batz time converter:

script_filters:
  - name: "Timezones"
    keyword: "tz"
    command: "batz"
    args: ["-j"]
    icon: "clock"

Usage:

tz New York
# Shows current time in New York
# Press Enter to copy timezone info

GitHub Pull Requests

script_filters:
  - name: "Pull Requests"
    keyword: "pr"
    command: "gh-pr-script"
    args: ["-j"]
    icon: "github"
    action: "xdg-open {value}"

Usage:

pr my-project
# Lists pull requests for my-project
# Press Enter to open PR in browser

Bookmark Manager

script_filters:
  - name: "Bookmarks"
    keyword: "bm"
    command: "bookmark-manager"
    args: ["--json"]
    icon: "bookmark"
    action: "echo -n {value}|wl-copy"
    secondary_action: "xdg-open {value}"

Usage:

bm documentation
# Filters bookmarks by "documentation"
# Enter: Copy URL
# Ctrl+Enter: Open in browser

Password Manager

script_filters:
  - name: "Passwords"
    keyword: "pw"
    command: "pass-json"
    icon: "lock"
    action: "copy"

Usage:

pw github
# Shows password entries matching "github"
# Press Enter to copy password

Web Search with Autocomplete

The scripts/search/search.py script in the repository provides live DuckDuckGo autocomplete suggestions while opening results in any configured search engine.

Install it first:

mkdir -p ~/.config/raffi/scripts/search
cp scripts/search/search.py ~/.config/raffi/scripts/search/search.py
chmod +x ~/.config/raffi/scripts/search/search.py

Then configure one entry per engine:

script_filters:
  - name: "Search DuckDuckGo"
    keyword: "ddg"
    command: "python3"
    args: ["~/.config/raffi/scripts/search/search.py", "duckduckgo"]
    icon: "web-browser"
    action: "xdg-open {value}"
    secondary_action: "copy"

  - name: "Search Google"
    keyword: "sg"
    command: "python3"
    args: ["~/.config/raffi/scripts/search/search.py", "google"]
    icon: "google"
    action: "xdg-open {value}"
    secondary_action: "copy"

Supported engines: google, duckduckgo, bing, brave.

Usage:

ddg rust async
# First item: raw query "rust async" → opens DuckDuckGo search
# Remaining items: DDG autocomplete suggestions
# Enter: open in browser
# Ctrl+Enter: copy URL to clipboard

Note

Suggestions are fetched from the DuckDuckGo autocomplete API (no API key required). On timeout or network error the script falls back to showing the raw query only.

Tip

This is different from the web_searches addon, which opens a URL directly without autocomplete. Use web_searches for instant access to a URL, and this script filter when you want live suggestions.

Creating a Script Filter

Here’s a simple example script in Python:

#!/usr/bin/env python3
import json
import sys

query = sys.argv[1] if len(sys.argv) > 1 else ""

items = [
    {
        "title": f"Result for: {query}",
        "subtitle": "This is a subtitle",
        "arg": f"https://example.com/search?q={query}",
        "icon": {"path": "/usr/share/icons/search.png"}
    }
]

print(json.dumps({"items": items}))

Make it executable and configure:

chmod +x my-filter.py

script_filters:
  - name: "My Filter"
    keyword: "mf"
    command: "./my-filter.py"
    action: "xdg-open {value}"

Keyboard Shortcuts

• Enter: Execute primary action
• Ctrl+Enter: Execute secondary action (if configured)
• Esc: Cancel and return to normal mode
• ↑/↓: Navigate through results

Requirements

Caution

Your script must output valid JSON to stdout. Any errors should go to stderr.

Note

Clipboard actions require wl-copy, xclip, or xsel

Note

Insert/type actions require wtype or ydotool

Tips

Tip

Test your script manually before adding to Raffi:

my-script -j "test query"

Tip

Use colors in output to highlight important information (ANSI codes are rendered)

Tip

Cache expensive operations in your script to improve performance

Tip

Set both action and secondary_action for maximum flexibility (e.g., copy vs. open)