Addon Configuration

The native UI includes several built-in addons that can be configured under the addons section of raffi.yaml. All addons are enabled by default.

Currency Converter

Converts between currencies using exchange rates from the Frankfurter API. Rates are cached for one hour.

Configuration

addons.currency.enabled boolean (default: true)

Enable or disable the currency converter addon.

addons:
  currency:
    enabled: true

addons.currency.trigger string (default: $)

Character that activates currency conversion.

Common values: $, €, £, ¥

addons:
  currency:
    trigger: "€"

addons.currency.default_currency string (default: USD)

Source currency used when none is specified in the query.

Must be a valid 3-letter ISO currency code (e.g., USD, EUR, GBP, JPY).

addons:
  currency:
    default_currency: EUR

addons.currency.currencies array[string]

List of available currencies for conversion.

If omitted, all currencies supported by the Frankfurter API are available. Specify a subset to limit options.

addons:
  currency:
    currencies: ["EUR", "USD", "GBP", "JPY", "CHF"]

Usage Examples

With trigger $ and default currency USD:

$10 to eur          → Converts 10 USD to EUR
$50 gbp to usd      → Converts 50 GBP to USD
$100eur to jpy      → Converts 100 EUR to JPY

With trigger € and default currency EUR:

€10 to usd          → Converts 10 EUR to USD
€50 to gbp          → Converts 50 EUR to GBP

Complete Example

addons:
  currency:
    enabled: true
    trigger: "€"
    default_currency: EUR
    currencies: ["EUR", "USD", "GBP", "JPY"]

Calculator

Evaluates mathematical expressions as you type. Results can be copied to the clipboard with Enter (requires wl-copy).

Configuration

addons.calculator.enabled boolean (default: true)

Enable or disable the calculator addon.

addons:
  calculator:
    enabled: true

Supported Operations

Basic arithmetic: +, -, *, /, %, ^
Functions: sqrt, sin, cos, tan, log, ln, exp, abs, floor, ceil
Constants: Standard mathematical constants

Usage Examples

2 + 2               → 4
10 * 5              → 50
sqrt(16)            → 4
sin(0.5)            → ~0.479
2^8                 → 256

No trigger character is needed; simply type a valid expression.

File Browser

Browses the filesystem with fuzzy filtering. Selecting a directory navigates into it; selecting a file opens it with xdg-open. Hidden files can be toggled with Ctrl+H.

Configuration

addons.file_browser.enabled boolean (default: true)

Enable or disable the file browser addon.

addons:
  file_browser:
    enabled: true

addons.file_browser.show_hidden boolean (default: false)

Show hidden files by default.

Can be toggled at runtime with Ctrl+H.

addons:
  file_browser:
    show_hidden: true

Usage

Type / to browse from root
Type ~ to browse from home directory
Text after the last / filters the current directory (e.g., /home/us filters /home/ by “us”)
Enter: Navigate into directory or open file
Alt+Enter: Copy file/directory path to clipboard
Tab: Autocomplete selected entry into search bar
Ctrl+H: Toggle hidden file visibility

Directories are listed first in accent color.

Example

addons:
  file_browser:
    enabled: true
    show_hidden: false

Script Filters

Script filters allow external commands to provide dynamic results using the Alfred Script Filter JSON format.

Configuration

addons.script_filters array[object] (default: [])

List of script filter configurations.

Each entry defines a keyword-triggered dynamic source.

Script Filter Fields

name string (required)

Display name shown during loading.

addons:
  script_filters:
    - name: "Timezones"

keyword string (required)

Text that activates the script filter.

addons:
  script_filters:
    - keyword: "tz"

command string (required)

Executable to run.

Supports tilde and environment variable expansion.

addons:
  script_filters:
    - command: "batz"

args array[string] (default: [])

Arguments passed to the command before the user’s query.

addons:
  script_filters:
    - command: "my-script"
      args: ["-j", "--verbose"]

icon string

Fallback icon name for results without their own icon.

addons:
  script_filters:
    - icon: "clock"

action string (default: copy)

Action to perform on Enter.

Special values:

copy - Copy to clipboard via wl-copy/xclip/xsel

insert - Type into focused app via wtype/ydotool

Any other string is executed as a shell command via sh -c, with {value} replaced by the selected value.

addons:
  script_filters:
    - action: "copy"                    # Copy to clipboard
    - action: "xdg-open {value}"        # Open in browser
    - action: "notify-send {value}"    # Show notification

**`secondary_action`** `string`

Action to perform on Ctrl+Enter.

  Accepts the same values as `action`. If omitted, Ctrl+Enter behaves the same as Enter.

  ```yaml
  addons:
    script_filters:
      - action: "copy"
        secondary_action: "xdg-open {value}"

env object (default: {})

Environment variables passed to the script process.

addons:
  script_filters:
    - command: "my-script"
      env:
        API_KEY: "secret"
        TZ_FORMAT: "short"

min_query_length integer

Minimum number of characters required after the keyword before the script executes.

When the query is shorter than this value, results are cleared and the script is not run. Useful for scripts that are slow or expensive with short queries.

addons:
  script_filters:
    - command: "my-script"
      min_query_length: 2   # only execute after 2 chars typed

JSON Output Format

The script must output JSON matching this structure:

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

JSON Fields:

title (required): Main text displayed for the item
subtitle (optional): Secondary text shown below the title
arg (optional): Value used in actions (falls back to title if omitted)
icon.path (optional): Absolute path to a PNG or SVG icon

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

Example: Timezone Converter

addons:
  script_filters:
    - name: "Timezones"
      keyword: "tz"
      command: "batz"        # https://github.com/chmouel/batzconverter
      args: ["-j"]
      icon: "clock"

Usage: Type tz paris to see current time in Paris.

Example: Bookmarks with Actions

addons:
  script_filters:
    - name: "Bookmarks"
      keyword: "bm"
      command: "my-bookmark-script"
      args: ["-j"]
      action: "copy"                    # Enter: Copy URL
      secondary_action: "xdg-open {value}"  # Ctrl+Enter: Open in browser
      icon: "bookmark"

Web Searches

Quick web searches via URL templates. Type a keyword followed by your query to open your browser with search results.

Configuration

addons.web_searches array[object] (default: [])

List of web search configurations.

Web Search Fields

name string (required)

Display name shown in the search row (e.g., “Search Google for…”).

addons:
  web_searches:
    - name: "Google"

keyword string (required)

Text that activates the web search.

addons:
  web_searches:
    - keyword: "g"

url string (required)

URL template with {query} placeholder.

The {query} placeholder is replaced with the search terms, automatically percent-encoded.

addons:
  web_searches:
    - url: "https://google.com/search?q={query}"

icon string

Icon name from your icon cache.

addons:
  web_searches:
    - icon: "google"

Example: Common Search Engines

addons:
  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"

    - name: "DuckDuckGo"
      keyword: "ddg"
      url: "https://duckduckgo.com/?q={query}"
      icon: "duckduckgo"

    - name: "GitHub"
      keyword: "gh"
      url: "https://github.com/search?q={query}&type=repositories"
      icon: "github"

    - name: "Wikipedia"
      keyword: "wiki"
      url: "https://en.wikipedia.org/wiki/Special:Search?search={query}"
      icon: "wikipedia"

Usage Examples

g rust traits       → Opens Google search for "rust traits"
ddg wayland        → Opens DuckDuckGo search for "wayland"
gh iced            → Opens GitHub search for "iced" repositories

Text Snippets

Reusable text values that can be searched and copied/typed. Snippets can come from inline definitions, external files, commands, or directories.

Configuration

addons.text_snippets array[object] (default: [])

List of text snippet source configurations.

Text Snippet Fields

name string (required)

Display name shown during loading (for command sources).

addons:
  text_snippets:
    - name: "Emails"

keyword string (required)

Text that activates this snippet source.

addons:
  text_snippets:
    - keyword: "em"

icon string

Icon name displayed next to each snippet.

addons:
  text_snippets:
    - icon: "mail"

snippets array[object]

Inline list of snippets.

Each snippet has:

name (string, required): Display name

value (string, required): Snippet content

addons:
  text_snippets:
    - snippets:
        - name: "Personal Email"
          value: "user@example.com"
        - name: "Work Email"
          value: "user@company.com"

**`file`** `string`

Path to a YAML file containing snippets.

  The file must contain a list of objects with `name` and `value` fields. Supports tilde and environment variable expansion. File contents are cached per session.

  ```yaml
  addons:
    text_snippets:
      - file: "~/.config/raffi/snippets.yaml"

File format:

- name: "Greeting"
  value: "Hello, world!"
- name: "Signature"
  value: "Best regards, User"

command string

Executable that outputs Alfred Script Filter JSON.

The title field maps to snippet name, arg to snippet value. Supports tilde and environment variable expansion.

addons:
  text_snippets:
    - command: "my-snippet-gen"

directory string

Path to a directory of .snippet files.

Each .snippet file format:

Description (first line)
---
Actual snippet content (everything after the separator)

Supports tilde and environment variable expansion. Files are cached per session.

addons:
  text_snippets:
    - directory: "~/.local/share/snippets"

args array[string] (default: [])

Arguments passed to the command.

addons:
  text_snippets:
    - command: "my-snippet-gen"
      args: ["-j", "--verbose"]

action string (default: copy)

Action to perform on Enter.

Special values:

copy - Copy to clipboard via wl-copy/xclip/xsel (default)

insert - Type into focused app via wtype/ydotool

Any other string is executed as a shell command via sh -c, with {value} replaced by the snippet value.

addons:
  text_snippets:
    - action: "copy"                    # Copy to clipboard
    - action: "insert"                  # Type into app
    - action: "notify-send {value}"    # Custom command

**`secondary_action`** `string` (default: `insert`)

Action to perform on Ctrl+Enter.

  Accepts the same values as `action`. Defaults to `insert` if omitted.

  ```yaml
  addons:
    text_snippets:
      - action: "insert"          # Enter: Type
        secondary_action: "copy"  # Ctrl+Enter: Copy

Note: Exactly one of snippets, file, command, or directory should be specified per entry.

Example: Inline Snippets

addons:
  text_snippets:
    - name: "Emails"
      keyword: "em"
      icon: "mail"
      action: "copy"
      snippets:
        - name: "Personal Email"
          value: "user@example.com"
        - name: "Work Email"
          value: "user@company.com"

Example: File-Based Snippets

addons:
  text_snippets:
    - name: "Templates"
      keyword: "tpl"
      icon: "document"
      file: "~/.config/raffi/snippets.yaml"

Example: Command-Based Snippets

addons:
  text_snippets:
    - name: "Dynamic"
      keyword: "dyn"
      icon: "terminal"
      command: "my-snippet-gen"
      args: ["-j"]

Example: Directory-Based Snippets

addons:
  text_snippets:
    - name: "Code Snippets"
      keyword: "sn"
      icon: "code"
      directory: "~/.local/share/snippets"

Example: Custom Actions

addons:
  text_snippets:
    - name: "URLs"
      keyword: "url"
      icon: "web-browser"
      action: "xdg-open {value}"        # Enter: Open in browser
      secondary_action: "copy"          # Ctrl+Enter: Copy URL
      snippets:
        - name: "GitHub"
          value: "https://github.com"
        - name: "Documentation"
          value: "https://docs.example.com"

Complete Addon Example

addons:
  currency:
    enabled: true
    trigger: "$"
    default_currency: USD
    currencies: ["USD", "EUR", "GBP", "JPY"]

  calculator:
    enabled: true

  file_browser:
    enabled: true
    show_hidden: false

  script_filters:
    - name: "Timezones"
      keyword: "tz"
      command: "batz"
      args: ["-j"]
      icon: "clock"
      min_query_length: 2
      env:
        TZ_FORMAT: "short"

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

  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"

    - name: "GitHub"
      keyword: "gh"
      url: "https://github.com/search?q={query}&type=repositories"
      icon: "github"

  text_snippets:
    - name: "Emails"
      keyword: "em"
      icon: "mail"
      action: "insert"
      secondary_action: "copy"
      snippets:
        - name: "Personal Email"
          value: "user@example.com"
        - name: "Work Email"
          value: "user@company.com"

    - name: "Templates"
      keyword: "tpl"
      icon: "document"
      file: "~/.config/raffi/snippets.yaml"