Addon Configuration

Addons are set up under addons: in raffi.yaml. Each addon’s own page lists its settings in a Configuration section; this page covers what they share and links to each one.

Almost every addon is on from the start. Three are the exception. Installed apps stay off unless you have no entries of your own, clipboard history turns itself on when CopyQ is running, and Slack stays off until you set enabled: true and give it a token. Set enabled: true or enabled: false on any addon to decide for yourself.

Closing After an Action

Every addon, and every entry under script_filters, web_searches and text_snippets, accepts close_on_action. It decides whether Raffi closes after you run something there, and it wins over general.close_on_action.

Most addons close Raffi unless told otherwise. Media controls, the audio switcher, Bluetooth and the process killer stay open so you can do several things in a row; they close only when you set close_on_action: true on the addon or in general. Anything that types or pastes into the window you came from closes Raffi first, whatever the setting says.

general:
  close_on_action: false   # stay open after most actions
addons:
  emoji:
    close_on_action: true  # but close after picking an emoji

All Addons

Addon	Key under addons:	How you reach it	Settings
Installed apps	apps	In the main list	Installed Apps
Calculator	calculator	Type a sum	Calculator
Currency converter	currency	$	Currency Converter
Unit conversion	units	Type 10 km to mi	Unit Conversion
Color converter	color	Type a color	Color Converter
World clock	world_clock	Type time in tokyo	World Clock
File browser	file_browser	/ or ~/	File Browser
Emoji picker	emoji	emoji	Emoji Picker below
Clipboard history	clipboard	clip	Clipboard History
System commands	system	sys	System Commands
Window switcher	windows	win	Window Switcher
Browser tabs	browser_tabs	tabs	Browser Tabs
Bookmarks	bookmarks	bm	Bookmarks
Browser history	browser_history	hist	Browser History
Media controls	media	media	Media Controls
Audio switcher	audio	audio	Audio Switcher
Bluetooth	bluetooth	bt	Bluetooth
Run in terminal	terminal	>	Run in Terminal
Kill process	kill	kill	Kill Process
Password store	pass	pass	Password Store
Bitwarden	bitwarden	bw	Bitwarden
Slack	slack	slack	Slack
Developer tools	devtools	dev	Developer Tools
Script filters	script_filters	A keyword you pick	Script Filters
Web searches	web_searches	A keyword you pick	Web Search
Text snippets	text_snippets	A keyword you pick	Text Snippets

Most addons with a keyword let you change it with trigger.

Keywords

Type a keyword followed by a space to open that addon. Typing sn on its own searches as usual, while sn opens the snippet source with that keyword.

While you type, Raffi lists the keywords that match at the top of the results, each with a short description. Press Enter or Tab on one to complete it and open the addon, so you never have to remember the exact keyword.

Suggestions start after three characters, so a single s leaves your results alone. A keyword typed in full, such as sn, is suggested right away. Change the threshold with keyword_min_chars:

addons:
  keyword_min_chars: 1   # suggest from the first character

The file browser (/, ~/) and the currency converter ($) open on their first character instead, so this setting does not affect them.

You can also type what you want instead of the keyword. A whole word such as volume, password, clipboard, lock or files lists the addon that handles it. These words only match in full, so they stay out of the way while you type a longer name. When nothing matches at all, Raffi lists the keywords whose description mentions your words, so switcher offers the window switcher.

Press Ctrl+/, or type ? on its own, to open help. It lists addon keywords in one section and keyboard shortcuts in another, and typing filters both. Escape or Ctrl+/ brings back what you had typed.

Emoji Picker

Type emoji and a space, then search by name. Enter copies the character and Ctrl+Enter types it into the window you came from.

The character lists are downloaded the first time you open the picker and kept for later.

addons:
  emoji:
    trigger: "em"
    action: "insert"
    secondary_action: "copy"
    data_files: ["emojis_smileys_emotion", "gitmoji", "nerd_font"]

enabled boolean (default: true)

trigger string (default: emoji)

action string (default: copy)

What Enter does: copy, insert, or a command to run, with {value} standing for the character.

secondary_action string (default: insert)

What Ctrl+Enter does, with the same choices.

data_files list (default: the standard emoji groups)

Which character lists to load, by name. Besides the emoji groups such as emojis_smileys_emotion or emojis_food_drink, you can add others like gitmoji or nerd_font.

close_on_action boolean (default: general.close_on_action, else true)

Typing a character in always closes Raffi first.

Complete Addon Example

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

  calculator:
    enabled: true

  units:
    enabled: true

  color:
    enabled: true

  world_clock:
    enabled: true

  devtools:
    enabled: true
    trigger: "dev"
    password_length: 20

  windows:
    enabled: true
    trigger: "win"

  browser_tabs:
    enabled: true
    trigger: "tabs"
    favicon_service: twenty

  media:
    enabled: true
    trigger: "media"
    close_on_action: false

  audio:
    enabled: true
    trigger: "audio"
    close_on_action: false

  kill:
    enabled: true
    trigger: "kill"

  bluetooth:
    enabled: true
    trigger: "bt"
    close_on_action: false

  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"