Documentation

Installation

Grab the latest .deb or .AppImage from GitHub Releases.

Debian / Ubuntu (.deb)

After downloading, install with APT (adjust filename to match release):

sudo apt install ./crest_0.2.6_amd64.deb

Other distros (.AppImage)

chmod +x crest_*.AppImage then run it. Ensure FUSE / libfuse is available on your distro if the AppImage requires it.

Global shortcuts & Wayland

Crest reads ~/.config/crest/config.json. The field global_shortcut sets the in-app global hotkey (default Super + Space). Syntax follows the Rust global-hotkey crate — put modifiers first, e.g. alt+Space, super+KeyK.

What to do on Wayland (recommended): open your desktop Settings → Keyboard → Custom shortcuts, bind your preferred chord, and set the command to crest. From v0.2.1+, Crest is single-instance: each launch toggles show/hide. That mimics Raycast-style behavior reliably.

From v0.2.2+, Crest may show a yellow hint banner inside the window when shortcuts are unlikely to work, with the same guidance.

Debugging: see ~/.local/share/crest/hotkey.log or run crest from a terminal for stderr.

Advanced: Setup via Terminal (GNOME)

If you're automating your setup or prefer the command line, you can register the shortcut directly into the GNOME GSettings database:

# 1. Register the custom shortcut path
gsettings set org.gnome.settings-daemon.plugins.media-keys \
  custom-keybindings "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"

# 2. Configure Name, Command, and Key Binding
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  name "Crest"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  command "crest"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  binding "<Super>space"

* Note: Replace custom0 with custom1, custom2, etc., if that slot is already taken.

Keyboard usage

• Type to fuzzy-search apps and other sources.
• ↑ / ↓ to move selection; Enter to run the primary action.
• Secondary actions: Ctrl + K.
• With an empty search field, Backspace cycles modes (clipboard, search, file mode, …).

Configuration & plugins

Main config: ~/.config/crest/config.json — includes global_shortcut, plugin_policy, and related options.

By default plugin_policy is "manifest": only extensions listed in ~/.config/crest/plugins/manifest.json load. Paths are resolved under that directory (no path traversal).

Set "plugin_policy": "open" only if you need the legacy model where every executable in the plugins folder is eligible — treat that folder as full trust.

Copy configs/plugins.manifest.example.json from the repo as a starting layout. Scripts must emit JSON Crest can deserialize into normal result rows.

Calculator, files & web

Calculator & units

Crest evaluates math inline (via fend-core): arithmetic, natural language like “30 percent of 20”, unit conversions, and bases — no leading = required when the query parses as math.

Currency

Live pair conversion (e.g. 1 usd to inr) uses a free exchange-rate source, cached at startup for ~24h. Small differences vs bank or Google rates are normal — query text is not sent to the network for this.

File mode

Prefix with /. Defaults index ~/Documents, ~/Downloads, ~/Desktop (hidden dirs and heavy dev folders skipped). Opens via xdg-open.

Web

Unmatched queries can offer DuckDuckGo search and inline snippets after a typing pause — see privacy below.

Troubleshooting

• Launcher does not open / shortcut dead — Wayland: bind crest at the desktop level; verify which crest in the shortcut command.
• Silent hotkey failure — read ~/.local/share/crest/hotkey.log.
• Plugins missing — check manifest.json entries, execute bits, and plugin_policy.
• Build from source issues — see README and CONTRIBUTING.md on GitHub.

Issues and feature discussion: GitHub Issues.