---
title: Addon Configuration
description: Configuration reference for built-in addons (currency, calculator, file browser, script filters, web searches, text snippets)
---
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.
## Keywords
Script filters, web searches, text snippets, and the emoji picker are reached by
typing their keyword followed by a space. Typing `sn` on its own searches your
launchers as usual, while `sn ` enters the snippet source.
While you type a keyword, Raffi lists the matching keywords at the top of the
results with a short description of what each one does. Pressing Enter or Tab on
one of those rows completes your input to `sn ` and drops you into the addon, so
you never have to remember the exact keyword.
The file browser (`/`, `~/`) and the currency converter (`$`) are prefix
triggers rather than keywords, and are not affected.
Press **Ctrl+/** in the native UI to list every keyword and trigger you have
available, each with its usage syntax. The list replaces the launcher entries,
typing narrows it, Enter or Tab on a row arms that keyword, and Escape closes
it.
## 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.
```yaml
addons:
currency:
enabled: true
```
**`addons.currency.trigger`** `string` (default: `$`)
Character that activates currency conversion.
Common values: `$`, `€`, `£`, `¥`
```yaml
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`).
```yaml
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.
```yaml
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
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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
```yaml
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](https://www.alfredapp.com/help/workflows/inputs/script-filter/json/).
### 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.
```yaml
addons:
script_filters:
- name: "Timezones"
```
**`keyword`** `string` (required)
Text that activates the script filter. Type it followed by a space, so `tz `
enters the filter while `tz` keeps searching launchers.
```yaml
addons:
script_filters:
- keyword: "tz"
```
**`command`** `string` (required)
Executable to run.
Supports tilde and environment variable expansion.
```yaml
addons:
script_filters:
- command: "batz"
```
**`args`** `array[string]` (default: `[]`)
Arguments passed to the command before the user's query.
```yaml
addons:
script_filters:
- command: "my-script"
args: ["-j", "--verbose"]
```
**`icon`** `string`
Fallback icon name for results without their own icon.
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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:
```json
{
"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
```yaml
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
```yaml
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...").
```yaml
addons:
web_searches:
- name: "Google"
```
**`keyword`** `string` (required)
Text that activates the web search. Type it followed by a space, so `g `
enters the search while `g` keeps searching launchers.
```yaml
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.
```yaml
addons:
web_searches:
- url: "https://google.com/search?q={query}"
```
**`icon`** `string`
Icon name from your icon cache.
```yaml
addons:
web_searches:
- icon: "google"
```
### Example: Common Search Engines
```yaml
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).
```yaml
addons:
text_snippets:
- name: "Emails"
```
**`keyword`** `string` (required)
Text that activates this snippet source. Type it followed by a space, so `em `
enters the source while `em` keeps searching launchers.
```yaml
addons:
text_snippets:
- keyword: "em"
```
**`icon`** `string`
Default emoji, icon name, or image path displayed next to each snippet.
A per-snippet `icon` overrides it; an unavailable icon falls back to this
default. `no_icons` hides both. Paths support tilde and environment variables.
```yaml
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, which may contain
[dynamic placeholders](/features/text-snippets/#dynamic-placeholders)
such as `{clipboard}` or `{date +1d}`
- `keyword` (string, optional): Abbreviation ranked first when typed exactly
- `icon` (string, optional): Emoji (for example `🏠`), icon name, or image path
```yaml
addons:
text_snippets:
- snippets:
- name: "Personal Email"
icon: "📨"
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:
```yaml
- 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, and the optional `keyword` field to the snippet keyword. An optional `icon.path` sets the item icon. `{shell:...}` placeholders are disabled for command output. Supports tilde and environment variable expansion.
```yaml
addons:
text_snippets:
- command: "my-snippet-gen"
```
**`directory`** `string`
Path to a directory of `.snippet` files.
Each `.snippet` file format:
```
Description (first line)
keyword: !abbr (optional)
icon: 🏠 (optional)
---
Actual snippet content (everything after the separator)
```
The optional headers can appear in either order. Supports tilde and environment variable expansion. Files are cached per session.
```yaml
addons:
text_snippets:
- directory: "~/.local/share/snippets"
```
**`args`** `array[string]` (default: `[]`)
Arguments passed to the command.
```yaml
addons:
text_snippets:
- command: "my-snippet-gen"
args: ["-j", "--verbose"]
```
**`action`** `string` (default: `copy`, or `hypr_paste` on Hyprland)
Action to perform on Enter. Inside Hyprland, an unset `action` becomes
`hypr_paste` when Raffi finds a window to paste into, and `copy` otherwise.
Special values:
- `copy` - Copy to clipboard via `wl-copy`/`xclip`/`xsel` (default outside Hyprland)
- `insert` - Type into focused app via `wtype`/`ydotool`
- `hypr_paste` - On Hyprland, copy with `wl-copy`, close Raffi, wait for the
original window to regain focus, and send Ctrl+V to that window (Ctrl+Shift+V
for terminals, see `general.terminal_classes`). Requires
Hyprland's Lua API, `hyprctl`, and `wl-clipboard`. Leaves the snippet on the
clipboard unless `restore_clipboard` is enabled; does not reposition
`{cursor}`. Marks the snippet sensitive so CopyQ and other clipboard managers
that honor the hint skip storing it. See
[Hyprland paste](/features/text-snippets/#default-actions).
Any other string is executed as a shell command via `sh -c`, with `{value}` replaced by the snippet value. The value is also exported as `$RAFFI_VALUE`; prefer `"$RAFFI_VALUE"` when the snippet may contain quotes or shell syntax, since `{value}` is substituted as raw text.
```yaml
addons:
text_snippets:
- action: "copy" # Copy to clipboard
- action: "insert" # Type into app
- action: "hypr_paste" # Paste into the original window on Hyprland
- action: 'notify-send "$RAFFI_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
```
**`restore_clipboard`** `boolean` (default: `false`)
For `action: "hypr_paste"` or `secondary_action: "hypr_paste"`, save the
previous plain-text clipboard and restore it one second after the shortcut
if Raffi's clipboard marker is still present. Requires `wl-paste`. Saving or
restoration failures do not block pasting. Snapshots are limited to 100 KiB of
UTF-8 text without NUL bytes; unavailable or non-text selections are skipped.
Rich-text formatting and images are not preserved. The delay is best effort
and may be too short for slow applications. This setting does not affect other
actions.
**`placeholders`** `boolean` (default: `true`)
Expand [dynamic placeholders](/features/text-snippets/#dynamic-placeholders) in snippet values. Set to `false` to use values exactly as written.
```yaml
addons:
text_snippets:
- file: "~/.config/raffi/literal-snippets.yaml"
placeholders: false
```
**Note:** Exactly one of `snippets`, `file`, `command`, or `directory` should be specified per entry.
### Example: Inline Snippets
```yaml
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
```yaml
addons:
text_snippets:
- name: "Templates"
keyword: "tpl"
icon: "document"
file: "~/.config/raffi/snippets.yaml"
```
### Example: Command-Based Snippets
```yaml
addons:
text_snippets:
- name: "Dynamic"
keyword: "dyn"
icon: "terminal"
command: "my-snippet-gen"
args: ["-j"]
```
### Example: Directory-Based Snippets
```yaml
addons:
text_snippets:
- name: "Code Snippets"
keyword: "sn"
icon: "code"
directory: "~/.local/share/snippets"
```
### Example: Custom Actions
```yaml
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
```yaml
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"
```