Text Snippets

The native interface supports text snippets, which let you define reusable text values that can be searched and copied to the clipboard or typed into applications.

Note

Text snippets are only available in native mode. They are not available when using Fuzzel mode.

Overview

Snippets can come from four different sources:

Inline

Defined directly in the config file

File

Loaded from an external YAML file

Command

Generated by running a command (Alfred JSON format)

Directory

Loaded from .snippet files in a directory

Usage

1. Type Keyword

   Type the configured keyword (e.g., em for emails)

2. Filter Results

   Continue typing to fuzzy-filter snippets by name

3. Select Snippet

   Use arrow keys to select the desired snippet

4. Execute Action

   • Enter: Default action (copy or insert)
     • Ctrl+Enter: Secondary action (if configured)

Configuration Sources

Inline Snippets

Define snippets directly in raffi.yaml:

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

Usage:

em personal
# Filters to "Personal Email"
# Press Enter to copy user@example.com

File Source

Load snippets from an external YAML file:

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

The snippet file (~/.config/raffi/snippets.yaml):

- name: "Greeting"
  value: "Hello, world!"

- name: "Signature"
  value: "Best regards, User"

- name: "Meeting Template"
  value: |
    Meeting Notes
    Date: [DATE]
    Attendees: [NAMES]
    Topics:
    -
    Action Items:
    -

Note

File-based snippets are cached per session for performance.

Command Source

Generate snippets dynamically from a command:

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

The command must output JSON in Alfred Script Filter format:

{
  "items": [
    {
      "title": "Current Date",
      "arg": "2024-03-15"
    },
    {
      "title": "Current Time",
      "arg": "14:30:00"
    }
  ]
}

Tip

The title field becomes the snippet name, and arg becomes the snippet value.

Directory Source

Load snippets from a directory of .snippet files:

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

Each .snippet file has this format:

Friendly Greeting
---
Hello! How are you doing today?

Professional Signature
---
Best regards,
John Doe
Software Engineer
john@example.com

Format:

• First line: Snippet name (description)
• ---: Separator
• After separator: Snippet content (value)

Note

Directory-based snippets are sorted alphabetically and cached per session.

Actions

Configure how snippets are used when selected:

Default Actions

Copy (Default)

action: "copy"

Copies snippet to clipboard using wl-copy, xclip, or xsel

Insert/Type

action: "insert"

Types snippet into focused app using wtype or ydotool

Custom Actions

Use command templates with {value} placeholder:

text_snippets:
  - name: "Commands"
    keyword: "cmd"
    action: "kitty sh -c {value}"
    snippets:
      - name: "System Update"
        value: "sudo pacman -Syu"

Primary and Secondary Actions

Configure different actions for Enter and Ctrl+Enter:

text_snippets:
  - name: "Emails"
    keyword: "em"
    icon: "mail"
    action: "insert"          # Enter: Type into app
    secondary_action: "copy"  # Ctrl+Enter: Copy to clipboard
    snippets:
      - name: "Personal Email"
        value: "user@example.com"
      - name: "Work Email"
        value: "user@company.com"

Configuration Fields

name string (required)

Display name shown during loading (for command sources)

keyword string (required)

Text that activates the snippet source

icon string

Icon name from your icon cache to display next to each snippet

snippets array

Inline list of snippets (each with name and value)

file string

Path to a YAML file containing snippets (cached per session)

command string

Executable that outputs Alfred Script Filter JSON

directory string

Path to a directory of .snippet files (cached per session)

args array

Arguments passed to the command

action string (default: copy)

Action on Enter:

• "copy": Copy to clipboard
• "insert": Type into focused app
• Command template with {value} placeholder

secondary_action string (default: insert)

Action on Ctrl+Enter. Accepts same values as action.

Caution

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

Examples

Email Addresses

text_snippets:
  - name: "Emails"
    keyword: "em"
    icon: "mail"
    snippets:
      - name: "Personal"
        value: "john@personal.com"
      - name: "Work"
        value: "john@company.com"
      - name: "GitHub"
        value: "john@users.noreply.github.com"

Code Snippets

text_snippets:
  - name: "Code Templates"
    keyword: "code"
    icon: "code"
    action: "insert"
    snippets:
      - name: "Rust Main"
        value: |
          fn main() {
              println!("Hello, world!");
          }

      - name: "Python Main"
        value: |
          if __name__ == "__main__":
              pass

Git Commands

text_snippets:
  - name: "Git Commands"
    keyword: "git"
    file: "~/.config/raffi/git-snippets.yaml"

- name: "Amend Commit"
  value: "git commit --amend --no-edit"

- name: "Push Force"
  value: "git push --force-with-lease"

- name: "Interactive Rebase"
  value: "git rebase -i HEAD~"

Dynamic Dates

Create a script that generates date snippets:

#!/usr/bin/env python3
import json
from datetime import datetime, timedelta

today = datetime.now()

items = [
    {"title": "Today", "arg": today.strftime("%Y-%m-%d")},
    {"title": "Yesterday", "arg": (today - timedelta(days=1)).strftime("%Y-%m-%d")},
    {"title": "Tomorrow", "arg": (today + timedelta(days=1)).strftime("%Y-%m-%d")},
    {"title": "ISO Timestamp", "arg": today.isoformat()},
]

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

text_snippets:
  - name: "Dates"
    keyword: "date"
    command: "python3 ~/.config/raffi/date-snippets.py"
    icon: "calendar"

Use Cases

Contact Information

- name: "Contact"
  keyword: "contact"
  snippets:
    - name: "Email"
      value: "user@example.com"
    - name: "Phone"
      value: "+1-555-0123"
    - name: "Address"
      value: "123 Main St, City, State 12345"

Frequently Used Commands

- name: "Shell Commands"
  keyword: "sh"
  action: "insert"
  snippets:
    - name: "Docker Cleanup"
      value: "docker system prune -af"
    - name: "Find Large Files"
      value: "du -sh * | sort -h"

Text Templates

- name: "Templates"
  keyword: "tpl"
  directory: "~/.config/raffi/templates"

With files like:

• meeting-notes.snippet
• bug-report.snippet
• email-signature.snippet

Programming Snippets

- name: "Code"
  keyword: "snippet"
  file: "~/.config/raffi/code-snippets.yaml"
  action: "insert"

Keyboard Shortcuts

• Enter: Execute primary action (default: copy)
• Ctrl+Enter: Execute secondary action (default: insert)
• Esc: Cancel and return to normal mode
• ↑/↓: Navigate through snippets

Requirements

Note

For copying: wl-copy (wl-clipboard), xclip, or xsel

Note

For typing/inserting: wtype or ydotool

Tips

Tip

Use file sources for large snippet collections to keep your main config clean

Tip

Command sources are perfect for dynamic content like dates, git branch names, or API responses

Tip

Directory sources work well for organizing snippets by category (each category in its own directory)

Tip

Set action: "insert" and secondary_action: "copy" for maximum flexibility

Complete Example

Here’s a full configuration with multiple snippet sources:

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

    # Templates from file
    - name: "Templates"
      keyword: "tpl"
      icon: "document"
      file: "~/.config/raffi/templates.yaml"
      action: "insert"

    # Dynamic dates from command
    - name: "Dates"
      keyword: "date"
      command: "date-snippets"
      icon: "calendar"

    # Code snippets from directory
    - name: "Code Snippets"
      keyword: "code"
      directory: "~/.config/raffi/snippets"
      action: "insert"
      secondary_action: "copy"