---
title: Quick Start
description: Get up and running with Raffi in minutes
---
import { Aside, Tabs, TabItem, Card, CardGrid, Steps } from '@astrojs/starlight/components';
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.
</Aside>
## Step 1: Create Your Configuration
<Steps>
1. **Create the config directory**
Raffi looks for its configuration at `~/.config/raffi/raffi.yaml`. Create the directory:
```bash
mkdir -p ~/.config/raffi
```
2. **Create a basic configuration file**
Create `~/.config/raffi/raffi.yaml` with a simple entry:
```yaml
version: 1
launchers:
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
Raffi supports two interface modes:
<Tabs>
<TabItem label="Fuzzel Mode (Default)">
Fuzzel mode uses the external Fuzzel launcher for a minimal, Wayland-native experience.
### 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
```
Or explicitly specify Fuzzel mode:
```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>
<TabItem label="Native Mode">
Native mode uses Raffi's built-in iced-based GUI with additional features like calculator, file browser, and more.
### Launch Native Interface
```bash
raffi -u native
```
### Choose a Theme
```bash
# Dark theme (default, Dracula-inspired)
raffi -u native -t dark
# Light theme (Rose Pine Dawn)
raffi -u native -t light
```
### Set as Default
To always use native mode, add this to your config:
```yaml
general:
ui_type: native
theme: dark
font_size: 20
window_width: 800
window_height: 600
```
</TabItem>
</Tabs>
## Step 3: Add Script Support
Raffi can execute inline scripts with any interpreter:
<Tabs>
<TabItem label="Bash Script">
```yaml
launchers:
hello_script:
script: |
echo "Hello from Bash!"
notify-send "Raffi" "Script executed successfully"
description: "Hello Script"
icon: "script"
```
</TabItem>
<TabItem label="Python Script">
```yaml
launchers:
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
launchers:
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>
### 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
- Alt+Enter: Copy path to clipboard
- Tab: Autocomplete
- Ctrl+H: Toggle hidden files
### 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
launchers:
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
launchers:
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
launchers:
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
launchers:
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>