---
title: Quick Start
description: Get up and running with Raffi in minutes
---
import { Aside, Tabs, TabItem, Card, CardGrid, Steps } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import keywordSuggestionScreenshot from '../../assets/screenshots/keyword-suggestion.png';
import keywordHelpScreenshot from '../../assets/screenshots/keyword-help.png';
This guide will help you configure and launch your first application with Raffi.
<Aside type="tip">
If you already have desktop apps installed, you can often just run `raffi` immediately. When no valid custom launchers are configured yet, Raffi falls back to auto-detected applications from your system `.desktop` files. To list those apps next to your own launchers later, see [Installed Apps](../features/installed-apps/).
</Aside>
## Step 1: Create Your Configuration
<Steps>
1. **Create the config directory**
Raffi reads its configuration from `~/.config/raffi/`. Create the directory:
```bash
mkdir -p ~/.config/raffi
```
2. **Add your launchers**
Create `~/.config/raffi/launchers.yaml` with a few entries. Each key is an entry name:
```yaml title="launchers.yaml"
firefox:
binary: firefox
icon: firefox
description: Firefox Web Browser
terminal:
binary: kitty
icon: kitty
description: Kitty Terminal
file_manager:
binary: nautilus
icon: folder
description: File Manager
```
3. **Test your configuration**
Run Raffi in print-only mode to verify the configuration:
```bash
raffi -p
```
This will display your configured entries without executing them.
</Steps>
<Aside type="note">
Entries are only shown if the binary exists in your PATH. Replace the binary names with applications you have installed.
</Aside>
## Step 2: Choose Your Interface
The built-in native interface is the default and recommended UI. The external
Fuzzel backend is deprecated and remains available as a legacy option for
existing setups and Fuzzel-only builds.
<Tabs>
<TabItem label="Native Mode (Default)">
Native mode uses Raffi's built-in iced-based GUI with additional features like calculator, file browser, and more.
### Launch Native Interface
```bash
raffi
```
### Choose a Theme
```bash
# Dark theme (default, Dracula-inspired)
raffi -u native -t dark
# Light theme (Rose Pine Dawn)
raffi -u native -t light
```
### Make the Choice Explicit
The standard build already uses native mode by default. To pin that choice in your config:
```yaml
general:
ui_type: native
theme: dark
font_size: 20
window_width: 800
window_height: 600
```
</TabItem>
<TabItem label="Legacy Fuzzel (Deprecated)">
Fuzzel mode uses the external Fuzzel launcher. This deprecated backend
remains available for existing setups.
### Install Fuzzel
First, ensure Fuzzel is installed:
<Tabs>
<TabItem label="Arch Linux">
```bash
sudo pacman -S fuzzel
```
</TabItem>
<TabItem label="Ubuntu/Debian">
```bash
sudo apt install fuzzel
```
</TabItem>
<TabItem label="Build from source">
```bash
git clone https://codeberg.org/dnkl/fuzzel.git
cd fuzzel
meson build
ninja -C build
sudo ninja -C build install
```
</TabItem>
</Tabs>
### Launch with Fuzzel
```bash
raffi -u fuzzel
```
### Configure Fuzzel Appearance
Customize Fuzzel's look in `~/.config/fuzzel/fuzzel.ini`:
```ini
dpi-aware=yes
font=RobotoMonoNerdFont-Thin:size=16
terminal=kitty
width=50
layer=overlay
exit-on-keyboard-focus-loss=no
inner-pad=15
[colors]
background=282a36ff
text=f8f8f2ff
match=8be9fdff
selection=44475add
border=bd93f9ff
```
</TabItem>
</Tabs>
## Step 3: Add Script Support
Raffi can execute inline scripts with any interpreter:
<Tabs>
<TabItem label="Bash Script">
```yaml title="launchers.yaml"
hello_script:
script: |
echo "Hello from Bash!"
notify-send "Raffi" "Script executed successfully"
description: "Hello Script"
icon: "script"
```
</TabItem>
<TabItem label="Python Script">
```yaml title="launchers.yaml"
check_disk:
binary: python3
script: |
import shutil
usage = shutil.disk_usage("/")
percent = (usage.used / usage.total) * 100
print(f"Disk usage: {percent:.1f}%")
description: "Check Disk Usage"
icon: "drive-harddisk"
```
</TabItem>
<TabItem label="Node.js Script">
```yaml title="launchers.yaml"
node_example:
binary: node
script: |
const os = require('os');
console.log(`Hostname: ${os.hostname()}`);
console.log(`Platform: ${os.platform()}`);
description: "System Info (Node)"
icon: "nodejs"
```
</TabItem>
</Tabs>
## Step 4: Window Manager Integration
Integrate Raffi with your Wayland compositor:
<Tabs>
<TabItem label="Sway">
Add to `~/.config/sway/config`:
```ini
set $menu raffi -p
set $super Mod4
bindsym $super+Space exec cmd=$($menu) && [ -n "$cmd" ] && swaymsg exec -- "$cmd"
```
Reload Sway config:
```bash
swaymsg reload
```
Now press `Super+Space` to launch Raffi!
</TabItem>
<TabItem label="Hyprland">
Add to `~/.config/hypr/hyprland.conf`:
```ini
$super = SUPER
bind = $super, R, exec, (val=$(raffi -pI); [ -n "$val" ] && hyprctl dispatch exec "$val")
```
Reload Hyprland config or restart Hyprland, then press `Super+R` to launch Raffi.
</TabItem>
<TabItem label="Other Compositors">
For other Wayland compositors, bind a key to a command that captures Raffi's output and
hands it to the compositor as a single argument:
```bash
cmd=$(raffi -p) && [ -n "$cmd" ] && swaymsg exec -- "$cmd"
```
Or for direct execution:
```bash
raffi
```
</TabItem>
</Tabs>
## Step 5: Explore Native Mode Features
<Aside type="note">
These features are only available when using the native interface (`-u native`).
</Aside>
### Keyword Help
Press **Ctrl+/** to open help, with addon keywords and actions in one section and
keyboard shortcuts in another. Typing filters both sections. Opening help
temporarily clears any existing search query so all entries are visible;
Escape or **Ctrl+/** restores the query. Press Enter or Tab on a keyword row to
use its completion instead.
<Image src={keywordSuggestionScreenshot} alt="Keyword suggestion row while typing a trigger" width={800} />
<Image src={keywordHelpScreenshot} alt="Keyword help list with shortcut and keyword details" width={800} />
### Calculator
Just start typing a mathematical expression:
```
2 + 2 * 5
sqrt(144) + log(100)
sin(90) * 50
```
Press Enter to copy the result to clipboard.
### Currency Converter
Type `$` followed by an amount and currency:
```
$100 to eur
$50 gbp to usd
$10eur to jpy
```
<details>
<summary>Configure currency converter</summary>
```yaml
addons:
currency:
enabled: true
trigger: "$"
default_currency: USD
currencies: ["USD", "EUR", "GBP", "JPY", "CAD"]
```
</details>
### File Browser
Navigate your filesystem by typing:
- `/` - Browse root directory
- `~` - Browse home directory
- `/home/user/Documents` - Browse specific path
**Keyboard shortcuts:**
- Enter: Open file/directory
- Ctrl+Enter: Run the secondary action (copy path by default)
- Tab: Autocomplete
- Backspace on a trailing `/`: Go up to the parent directory
- `~/` or `/` after a `/`: Start over from home or the root
- Ctrl+H: Toggle hidden files
- Ctrl+O: Open the selected file or directory with `xdg-open`
- Ctrl+B: Open the current directory in a file manager
- Ctrl+Y: Copy the selected path to the clipboard, regardless of configured actions
- Ctrl+Alt+Y: Copy a supported image file to the clipboard
- Ctrl+S: Cycle the sort order (name, modified, created)
- Ctrl+J / Ctrl+K: Scroll the preview pane
### Web Searches
Add web searches to your config:
```yaml
addons:
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}"
icon: "github"
- name: "Wikipedia"
keyword: "wiki"
url: "https://en.wikipedia.org/wiki/{query}"
icon: "wikipedia"
```
Then type:
```
g wayland protocol
gh user/repo
wiki rust programming
```
## Common Use Cases
<details>
<summary>Launch applications with custom arguments</summary>
```yaml title="launchers.yaml"
firefox_private:
binary: firefox
args: [--private-window]
icon: firefox
description: Firefox Private Window
code_workspace:
binary: code
args: [~/projects/myapp]
icon: vscode
description: Open MyApp in VS Code
```
</details>
<details>
<summary>Conditional entries (show only when available)</summary>
```yaml title="launchers.yaml"
gnome_tweaks:
binary: gnome-tweaks
description: GNOME Tweaks
icon: gnome-tweak-tool
ifenveq: [DESKTOP_SESSION, GNOME]
wayland_only_app:
binary: my-wayland-app
description: Wayland App
icon: wayland
ifenvset: WAYLAND_DISPLAY
docker_compose:
binary: docker-compose
description: Docker Compose
icon: docker
ifexist: docker-compose
```
</details>
<details>
<summary>Path expansion and environment variables</summary>
```yaml title="launchers.yaml"
custom_script:
binary: ${HOME}/bin/my-script
args: ["${XDG_DATA_HOME}/files", "~/Documents"]
icon: ~/icons/custom.png
description: My Custom Script
ifexist: ~/bin/my-script
```
</details>
<details>
<summary>System actions</summary>
```yaml title="launchers.yaml"
lock_screen:
binary: swaylock
args: [-f, -c, "000000"]
icon: system-lock-screen
description: Lock Screen
suspend:
binary: systemctl
args: [suspend]
icon: system-suspend
description: Suspend to RAM
poweroff:
binary: systemctl
args: [poweroff]
icon: system-shutdown
description: Power Off
```
</details>
## Useful Commands
<Tabs>
<TabItem label="Print command without executing">
```bash
raffi -p
```
</TabItem>
<TabItem label="Use custom config file">
```bash
raffi -c ~/.config/raffi/work.yaml
```
</TabItem>
<TabItem label="Refresh icon cache">
```bash
raffi -r
```
</TabItem>
<TabItem label="Disable icons (faster startup)">
```bash
raffi -I
```
</TabItem>
<TabItem label="Native mode with initial query">
```bash
raffi -u native -i "firefox"
```
</TabItem>
<TabItem label="Set default script interpreter">
```bash
raffi --default-script-shell /bin/zsh
```
</TabItem>
</Tabs>
## Next Steps
<div class="nav-cards">
<CardGrid>
<a href="../configuration/overview/">
<Card title="Configuration Overview" icon="setting">
Explore all configuration options and advanced features
</Card>
</a>
<a href="../features/script-filters/">
<Card title="Script Filters" icon="magnifier">
Extend Raffi with dynamic external commands
</Card>
</a>
<a href="../features/themes/">
<Card title="Theme Customization" icon="star">
Customize the native interface colors and appearance
</Card>
</a>
<a href="../reference/cli-options/">
<Card title="CLI Options" icon="laptop">
Browse all command-line flags and options
</Card>
</a>
</CardGrid>
</div>
<style>
{`
.nav-cards a {
text-decoration: none !important;
color: inherit;
display: flex;
height: 100%;
}
.nav-cards a article {
flex: 1;
transition: all 0.2s ease-in-out;
cursor: pointer;
display: flex;
flex-direction: column;
gap: 1rem;
border: 1px solid var(--sl-color-gray-5);
background-color: var(--sl-color-black);
}
.nav-cards a article .title {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 1rem;
font-size: 1.2rem;
}
.nav-cards a article .title .icon {
font-size: 2.5rem !important; /* Huge icons */
color: var(--sl-color-purple);
background: var(--sl-color-purple-low);
padding: 0.5rem;
border-radius: 0.5rem;
border: 1px solid var(--sl-color-purple);
}
.nav-cards a:hover article {
border-color: var(--sl-color-text-accent);
background-color: var(--sl-color-gray-6);
}
`}
</style>