# Vicinae

> Vicinae is a cross-desktop, keyboard-driven application launcher for Linux. It supports extensions, theming, clipboard management, and more.

## Installation

# Vicinae

Vicinae is a keyboard-driven command launcher for Linux and macOS, inspired by [Raycast](https://www.raycast.com/). It puts common actions within keyboard reach: launching apps, switching windows, managing clipboard history, searching files, and more.

![](./main.png)

## Getting started

Install Vicinae on [Linux](https://docs.vicinae.com/install/linux) or [macOS](https://docs.vicinae.com/install/macos) and then follow the quickstart guide for your environment. If you want to learn a bit more about Vicinae, continue reading.

## Philosophy

Vicinae aims to be a shortcut for most simple actions on your system. It ships with a broad feature set and integrates seamlessly with native OS features like window management and clipboard. With minimal configuration, it works as a clipboard manager, window switcher, app launcher, calculator, web searcher, and more.

For anything too niche for the core, Vicinae can be extended via [dmenu mode](https://docs.vicinae.com/dmenu), [script commands](https://docs.vicinae.com/scripts/getting-started), or [full extensions built with React and TypeScript](https://docs.vicinae.com/extensions/introduction).

Extensions made by the [community](https://github.com/vicinaehq/extensions) can be installed from vicinae itself in a few clicks.

## Performance

Vicinae is built with performance in mind. When given the choice, vicinae will prefer to cache things in memory to lower CPU usage in order to keep battery drain minimal and remain snappy. The amount of memory vicinae really needs to function properly is generally lower than what most process monitors report. [Read more](https://docs.vicinae.com/faq#vicinae-uses-a-lot-of-ram).

## Raycast compatibility

One of Vicinae's flagship features is its compatibility with the Raycast ecosystem. Currently Vicinae has decent support for many Raycast extensions. Your mileage will vary depending on the extension, but simpler ones work well. Vicinae also implements script commands that mimic most of the Raycast feature of the same name.

The design is similar, but Vicinae does some things differently and unlocks things that Raycast locks behind a paywall, such as theming and window management APIs.

---

# Install on Linux

All the ways to install Vicinae on Linux: from your distribution's package repositories, using the installation script, or [building from source](https://docs.vicinae.com/build). 

## Package repositories

The most direct way to install Vicinae, if your distribution is covered. If it's not, use the [install script](#install-script) instead.

### Arch Linux (AUR)

Vicinae is available on the Arch User Repository (AUR) in three variants:

* **Source build**
  * [vicinae](https://aur.archlinux.org/packages/vicinae) – stable release, compiled from source
  * [vicinae-git](https://aur.archlinux.org/packages/vicinae-git) – latest development version, compiled from source

* **Prebuilt binary**
  * [vicinae-bin](https://aur.archlinux.org/packages/vicinae-bin) – stable release, precompiled binary

You can install Vicinae using your preferred AUR helper.

```bash
yay -S vicinae-bin
```

### Gentoo

Thanks to [jaredallard](https://github.com/jaredallard) for providing an [ebuild](https://github.com/jaredallard/overlay/tree/main/gui-apps/vicinae) through his overlay!

```bash
eselect repository add jaredallard-overlay git https://github.com/jaredallard/overlay.git
emerge --sync jaredallard-overlay
emerge gui-apps/vicinae
```

### Fedora and Derivatives

#### COPR

Vicinae is packaged on [COPR](https://copr.fedorainfracloud.org/coprs/quadratech188/vicinae/).

```bash
dnf copr enable quadratech188/vicinae
dnf install vicinae
```

#### Terra

Vicinae is also availible from [Terra](https://terra.fyralabs.com).

Start with installing Terra:

```bash
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```

Then install Vicinae:

```bash
sudo dnf install vicinae
```

On Fedora Atomic:

```bash
curl -fsSL https://github.com/terrapkg/subatomic-repos/raw/main/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo
sudo rpm-ostree install terra-release vicinae
```

Bazzite users don't need to install Terra. Just set `enabled` to `1` in `/etc/yum.repos.d/terra.repo` then use `rpm-ostree`:

```bash
sudo rpm-ostree install vicinae
```

### NixOS

Vicinae ships its own Nix flake and Home Manager module. See the dedicated [NixOS page](https://docs.vicinae.com/nixos).

## Install script

If your distribution is not covered above, Vicinae can be installed using an automated installation script that provides a hassle-free setup experience with minimal configuration required.

If Vicinae is already packaged by your distribution, you should install it through your package manager instead for better system integration and automatic updates.

Installation script by @dagimg-dot

### Quick Install

Run the following command to install Vicinae:

```bash
curl -fsSL https://vicinae.com/install | bash
```

The above command will prompt you to enter your sudo password, as elevated privileges are required to install Vicinae under `/usr/local`, which is the default installation prefix.
Note that it is possible to install Vicinae without root access, although it requires more setup. More on that below.

The installation script will automatically:

* Download the latest AppImage from GitHub releases
* Extract Vicinae and all its runtime dependencies to `/usr/local/lib/vicinae`
* Create symbolic links for binaries in your PATH
* Install desktop files, icons, and default themes
* Set up `vicinae-node` for seamless TypeScript extension support. This is a regular Node.js binary included to run extensions.

After installation completes, verify it was successful:

```
$> vicinae version
Version v0.16.2 (commit b99015bc2)
Build: GCC 15.2.0 - Release - LTO
Provenance: appimage
```

### Update

To update Vicinae, run the installation script again. It will detect your existing installation (if using the same prefix) and update it.

```bash
curl -fsSL https://vicinae.com/install | bash
```

### Uninstall

To uninstall Vicinae, run the installation script with the `--uninstall` argument:

```bash
curl -fsSL https://vicinae.com/install | bash -s -- --uninstall
```

### Install with custom prefix

By default, the script tries to install Vicinae under `/usr/local`, but for users with specific constraints (e.g., no root access), this might not be desirable.

To accommodate these users, the script provides a `--prefix` option:

```bash
curl -fsSL https://vicinae.com/install | bash -s -- --prefix ~/.local
```

#### Custom prefix caveats

In order to have a fully working installation of Vicinae, you need to make sure that:

* The Vicinae server knows where to find the `vicinae-node` binary. If you set your PATH in `~/.bashrc` or `~/.zshrc`, the Vicinae server might not have the correct PATH set, as it might be started before those files are sourced.
* The Vicinae desktop file that declares the `x-scheme-handler/vicinae` and `x-scheme-handler/raycast` MIME type associations should be searchable by the standard XDG tooling. You can verify this is working by opening any Vicinae deeplink, e.g., `xdg-open vicinae://toggle`.
  If this is not working, some features such as the OAuth extension flow will not work.

## Build from source

If none of the above fits your needs, you can always [build Vicinae from source](https://docs.vicinae.com/build).

---

# Install on macOS

Vicinae ships as a notarized `.dmg` for Apple Silicon Macs. 

macOS support is in **beta** since `v0.23.0`. All current Vicinae features are supported on macOS. Please report anything odd using the "Report a Vicinae bug" command.

## Requirements

* macOS Tahoe (26) or newer
* An Apple Silicon Mac: Intel Macs are not supported

## Install from DMG

Download [Vicinae.dmg](https://github.com/vicinaehq/vicinae/releases/latest/download/Vicinae.dmg) from the [latest release](https://github.com/vicinaehq/vicinae/releases/latest), open it, and drag `Vicinae.app` into your `Applications` folder.

The app is notarized, so no Gatekeeper workaround is needed: just launch it like any regular app. On first launch, an onboarding process will guide you through the initial setup.

### CLI usage

You can access the `vicinae` CLI by symlinking it from the bundle like so:

```bash
ln -sf /Applications/Vicinae.app/Contents/MacOS/vicinae-cli ~/.local/bin/vicinae
```

### Update

Vicinae will inform you when an update is ready to install.

## Homebrew install

You can install the cask for Vicinae as follows:

```bash
brew install --cask vicinae
```

This assumes you will handle updates using `brew` as Vicinae will not propose you to manually update if you installed it from homebrew.

Note that the `vicinae` CLI is also automatically installed and linked for you.

---

# Build from source

This guide will teach you how to install Vicinae from source and build an optimized version of the binary. 

## Why build from source

Vicinae is a decently sized mostly C++ code base. As such, compiling it can be quite resource demanding and time consuming, in particular if you enable specific optimizations such as LTO.

The main reward for compiling it yourself is the ability to compile Vicinae with [optimizations that are specific to your CPU model](https://docs.vicinae.com/build#optimized-build), provided that it's recent enough. And also, it's fun 😏.

If your goal is to get Vicinae up and running on your system as quickly as possible please consider [installing from a repository](https://docs.vicinae.com/install/linux#package-repositories) if your distribution is supported or [installing from the script](https://docs.vicinae.com/install/linux#install-script) if that is not the case.

## Build requirements

To build Vicinae, you need a working C++23-capable compiler. We mostly make use of `gcc` (v15+) but `clang` should also work and is the supported way to [build for macOS](https://docs.vicinae.com/build-macos).

You will also need a few dependencies, listed below.

If you distribution does not appear in this list, you are on your own to figure out the exact packages to install.
If you still manage to build it, don't forget to contribute to this documentation by adding your list here!

```bash {{ title: 'Arch Linux' }}
pacman -Syu			\
    base-devel 		\
    cmake			\
    ninja			\
    nodejs			\
    npm				\
    qt6-base		\
    qt6-svg			\
    protobuf		\
    cmark-gfm		\
    layer-shell-qt 	\
    libqalculate 	\
    minizip			\
    qtkeychain-qt6	\
    rapidfuzz-cpp \
    icu
```

```bash {{ title: 'Ubuntu' }}
apt install -y \
    build-essential \
    cmake \
    ninja-build  \
    nodejs  \
    npm \
    qt6-base-dev \
    qt6-svg-dev \
    qt6-wayland-dev \
    libqt6svg6  \
    libprotobuf-dev \
    cmark-gfm \
    layer-shell-qt  \
    liblayershellqtinterface-dev \
    libqalculate-dev  \
    libminizip-dev \
    libabsl-dev \
    libcmark-gfm-dev \
    zlib1g-dev \
    qtkeychain-qt6-dev  \
    librapidfuzz-cpp-dev \
    libicu-dev
```

```bash {{ title: 'Fedora' }}
dnf install -y \
    cmake \
    g++ \
    git \
    mold \
    ninja-build \
    nodejs-npm \
    'cmake(Qt6Core)' \
    'cmake(Qt6Qml)' \
    'pkgconfig(openssl)' \
    'cmake(Qt6Core)' \
    'cmake(Qt6Network)' \
    'cmake(Qt6Svg)' \
    'cmake(Qt6Concurrent)' \
    'cmake(Qt6Quick)' \
    'cmake(Qt6Qml)' \
    'cmake(Qt6GuiPrivate)' \
    'cmake(Qt6QuickDialogs2)' \
    'cmake(Qt6QuickControls2)' \
    'cmake(Qt6ShaderTools)' \
    'cmake(Qt6LinguistTools)' \
    'cmake(KF6SyntaxHighlighting)' \
    'cmake(LayerShellQt)' \
    'pkgconfig(xcb-keysyms)' \
    'pkgconfig(wayland-protocols)' \
    'cmake(Qt6Keychain)' \
    'pkgconfig(libqalculate)' \
    'qt6qml(org.kde.layershell)' \
    'nodejs(engine)'
```

```bash {{ title: 'Gentoo Linux' }}
emerge -av			\
	qtkeychain		\
	qtbase			\
	minizip-ng		\
	rapidfuzz-cpp	\
	layer-shell-qt	\
	libqalculate	\
	nodejs			\
	cmake			\
	cmark-gfm		\
	dev-qt/qtsvg	\
	protobuf		\
	dev-build/ninja \
	dev-libs/icu
```

## Recommended build tools

In order to make building and rebuilding Vicinae easier we recommend installing the following:

* Install `ccache` to automatically cache most compilations and significantly decrease build times.
* Install the `mold` linker to link the Vicinae binary significantly faster.

All you need is to install these tools, the Vicinae build system will take care of the rest for you.

## Build Flags

Several build flags are available to tweak what features are built into the final binary.
The best way to know about them is to read the beginning of the top level `CMakeLists.txt`.

Flags are easily identified by the use of the `option` cmake function:

```cmake
option(LTO "Enable Link Time Optimization (LTO). This will result in better performance, but greatly increased compile time." OFF)
option(NOSTRIP "Never strip debug symbols from the binary, even in release mode. Note that symbols are never stripped for debug releases." OFF)
option(USE_SYSTEM_PROTOBUF "Use system protobuf instead of building it from source" ON)
option(USE_SYSTEM_ABSEIL "Use system abseil (libabsl) instead of building it from source" ON)
option(USE_SYSTEM_CMARK_GFM "Use system cmark-gfm (github's fork of cmark) instead of building it from source" ON)
```

You can enable or disable a given option by passing a `-D<OPTION>=ON/OFF` flag to the `cmake` program during the *configuration* step. See the CMake code examples below.

## About static linking

Although Vicinae does not support being built in a fully static way, we provide the option to statically link against libraries that bump version often
or are generally not easy to install through traditional means.

The main goal of this is to make pre-built binaries more portable across different distributions that ship different versions of the same package.

For instance, `libprotobuf` updates very often and offers no retro-compatibility. This essentially means that the distributed binaries become outdated as soon as the distribution updates
its protobuf version. By statically linking against protobuf, we embed a given version of protobuf in the binary, and this specific, local version is the one going to be used for the entire lifetime of the binary.

If building from source you have very few reasons to statically link against libraries. This is mostly intended to help people packaging Vicinae as a standalone binary.

For reference, this is the CMake configure command we use to build our releases:

```bash
cmake -G Ninja .. \
	-DCMAKE_POLICY_VERSION_MINIMUM=3.5  \
	-DLTO=ON \
	-DUSE_SYSTEM_PROTOBUF=OFF \
	-DUSE_SYSTEM_ABSEIL=OFF \
	-DUSE_SYSTEM_CMARK_GFM=OFF \
```

This will:

* instruct `cmake` to download a copy of a specific version of `protobuf`, `abseil`, `cmark-gfm` and `minizip-ng`
* build them alongside the main Vicinae code base
* link them all together as a single binary

We may add static linking options for other libraries down the road.

## Get the source code

First, clone the repository and go to the source directory:

```bash {{ title: 'Clone repo' }}
git clone https://github.com/vicinaehq/vicinae.git && cd vicinae
```

## Release Build

This is a generic, unoptimized build. If you are looking to build an optimized version for your specific system, read further.

To build a generic release build without LTO enabled:

```bash {{ title: 'Make' }}
make release
```

```bash {{ title: 'CMake' }}
cmake -G Ninja -B build
cmake --build build 
```

## Optimized Release Build

If you want to squeeze out the most performance you can out of Vicinae, you can enable a few optimization during configuration:

```bash {{ title: 'Make' }}
make host-optimized
```

```bash {{ title: 'CMake' }}
CXXFLAGS="${CXXFLAGS} -march=native" cmake -DLTO=ON -G Ninja -B build
cmake --build build 
```

* `-DLTO=ON` will enable link-time optimizations. This can greatly improve performance, but linkage will take a **lot** more time.
* `-march=native` compiles with all optimizations supported by the executing CPU. The resulting binary will only be able to be run on systems that support the same CPU flags.

Generally speaking, you will be trading compilation time and portability for more performance.

Binary releases are always compiled with link-time optimizations.

## Debug Build

You want a debug build when you are trying to troubleshoot an issue or generally contribute to Vicinae:

```bash {{ title: 'Make' }}
make debug
```

```bash {{ title: 'CMake' }}
cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja -B build
cmake --build build 
```

This will compile with `-g3`, enable sanitizers (asan + ubsan) and QT debug logs.

## Install built binaries

Once Vicinae is built, install it to standard system directories:

```bash {{ title: 'Make' }}
sudo make install
```

```bash {{ title: 'CMake' }}
sudo cmake --install build --prefix "$HOME/.local" 
```

---

# Build for macOS from source

This page explains how to build Vicinae for macOS from source.&#x20;

macOS support is in **beta**. If you just want to use Vicinae on your Mac, download the notarized `.dmg` from the [install page](https://docs.vicinae.com/install/macos) instead of building from source.

## Requirements

* A C++23-capable compiler. The macOS build is tested on **macOS Tahoe** with **AppleClang 21**. Older toolchains are not tested and may not work.
* [Homebrew](https://brew.sh) to install dependencies.

## Get the sources

Clone and build:

```bash
git clone https://github.com/vicinaehq/vicinae.git && cd vicinae
```

## Install dependencies

From the source tree, install all build dependencies:

```bash
make mac-deps
```

This installs the build toolchain via Homebrew and **Qt** from the official binaries (via [aqtinstall](https://github.com/miurahr/aqtinstall)) into `~/Qt`. You can override the Qt version with the `QT_VERSION` environment variable.

The build system automatically picks up the most recent Qt installation found under `~/Qt`. If you want to use a Qt installed somewhere else, pass `-DQT_DIR=/path/to/qt` when configuring with CMake. You can also install QT using Homebrew if you want to.

## Build

```bash {{ title: 'Make' }}
make release
```

```bash {{ title: 'CMake' }}
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build
```

The resulting binaries are placed under `build/bin`: `vicinae-server` (the launcher itself) and `vicinae` (the CLI).

## Assemble the app bundle

You can assemble an `.app` bundle and install it:

```bash
make mac-bundle
mv build/Vicinae.app /Applications
```

---

# Build AppImage from source

The intended way to consume the AppImage build is to install Vicinae using the [script](https://docs.vicinae.com/install/linux#install-script). This page documents how to build the AppImage from source using the AppImage build environment. This page is mostly intended for Vicinae developers.

## Why AppImage

Vicinae is an app that relies on a lot of bleeding edge C++ and Qt features. As such, building from source or using prebuilt binaries is mostly reserved to people running very bleeding edge systems such as Arch, NixOS, Gentoo, as other systems generally have very out of date packages.

This is obviously not ideal, as many users run distributions such as Ubuntu, Fedora, Linux Mint which fall into that category.

One common solution to this problem is simply to bundle most of the dependencies with the app, so that we can ignore the out of date aspect for the most part. This is essentially what an AppImage is: an app bundle.

There are obviously cons to bundling most dependencies compared to using system ones, so users that can should use prebuilt binaries or build from source instead. That's a trade-off.

Also, unlike flatpaks, AppImage and AppDirs do not perform any kind of sandboxing which doesn't play well with an application launcher like Vicinae.

### GLibc versioning

One of the few things that can't be bundled is the glibc that is used by the system to interface with the kernel. Glibc is backwards compatible. This means that in order to maximize compatibility, we need to build the AppImage in an environment that has a rather old glibc so that every system that has that version of glibc or higher can successfully run the AppImage. All the dependencies that are bundled should also be compiled against that version of glibc. This is why we need to build the AppImage on an old system. In Vicinae's case, we settled on an ubuntu:22.04 image which should support a lot of modern distributions.

A consequence of that is that if we require any modern dependency (that is thus unavailable to us using apt) we need to compile it ourselves. For Vicinae, that involves compiling a lot of things, such as:

* the compiler itself (gcc-15), so that we can have access to modern C++ features we rely on.
* Recent Qt version, on par with what's available on bleeding edge distros
* Various tools and libraries needed to build up-to-date stuff such as cmake, protobuf, etc.

### Containerization

In order to easily encapsulate the build environment for the AppImage we just use a [Dockerfile](https://github.com/vicinaehq/vicinae/blob/main/scripts/runners/appimage/AppImageBuilder.Dockerfile) that creates a build environment ready to build appimages.

It's then pushed on DockerHub tagged as `vicinae/appimage-build-env`.

## Build AppImage

### Prerequisites

* Docker
* AppImage stuff (libfuse, etc...)

All the required libraries and compiler are available inside the image so system libraries are irrelevant.

### Run build environment (from DockerHub)

From the Vicinae source tree, just run:

```bash
make appimage-build-env-run
```

From there you should be able to build the AppDir and AppImage by running:

```shell
make clean # make sure the build tree is clean
make appimage
```

### Build build environment

If for some reason you can't fetch the image from DockerHub, you can build the image locally by running:

```bash
make appimage-build-env
```

For the reasons mentioned above, building this image can take a very long time depending on hardware specs, so it is recommended to use the image uploaded to DockerHub instead.

---

## Quickstart

# macOS quickstart

Tips and tricks on getting started with Vicinae on macOS.

## Permissions

### Required permissions

The first time you start Vicinae, you will be greeted by an onboarding step asking you to give basic permissions needed for Vicinae to work in optimal settings.

* The accessibiltiy permission is required in order to implement basic features such as paste, snippets, and window management.
* Full disk access is required so that the Spotlight integration can find all your files, including those present in user protected directories. Some extensions may also need it, e.g the Apple Notes extension requires FDA in order to read the SQLite database the Notes app uses.
* The notifications permissions can be granted to Vicinae as some extensions, especially those kicking of tasks in the background, can use the `sendDesktopNotification` API to send you proper desktop notifications.

You are not obligated to give any permission to start using Vicinae, but all of the above is strongly recommended.

![](https://docs.vicinae.com/macos-onboarding.png)

Vicinae may prompt you for additional permissions on a per use case basis, e.g if some command requires the use of AppleScript.

### Reset permissions

As for any other Mac app, you can reset all permissions granted to Vicinae with `tccutil`:

```bash
tccutil reset All com.vicinaehq.Vicinae
```

This alone won't reset the onboarding state, though. To do so:

```bash
rm -f ~/.local/state/vicinae/onboarding.json
```

Then, you can restart Vicinae and you will get the onboarding step again.

## Autostart

If you didn't unselect it during onboarding, Vicinae will automatically create a login item so that it gets started on boot.

## Appearance

### Liquid glass VS vibrancy

Vicinae supports two distinct materials for its main window:

* Liquid glass, the new material introduced with macOS Tahoe
* Vibrancy or blur, which has been traditionally used by panels in previous macOS versions

The default is liquid glass, and it can be changed in the settings. You can also adjust the opacity of the window, which may give the glass/vibrancy a slightly different look depending on what's behind it.

Although Apple doesn't recommend stacking liquid glass surfaces on top of each other, Vicinae also uses liquid glass for its popup windows such as the action panel or dropdowns. We think it looks good.

![the Vicinae main window with the liquid glass material](https://docs.vicinae.com/liquid-glass.png)

## Nix

Nix users will want to configure most of of the above in a declarative manner. Vicinae, as built by the nix flake, will present the following differences:

* No onboarding step, permissions should be granted declaratively
* No login item created on first startup, a proper launchd integration must be used
* SoulverCore calculator backend is not automatically downloaded and included in the bundle

---

# Hyprland Lua Quickstart

This guide shows the best way to quickly get started with Vicinae on [Hyprland](https://hypr.land/).

This page is for Hyprland 0.55+ Lua configuration. If you are still using hyprlang syntax, see [Hyprland Quickstart](https://docs.vicinae.com/quickstart/hyprland).

## Main configuration

Add the following to your Hyprland configuration, and you are good to go (unless you use uwsm to manage Hyprland, see below).

```lua
-- ~/.config/hypr/hyprland.lua

local mainMod = "SUPER"

-- autostart
hl.on("hyprland.start", function()
  hl.exec_cmd("vicinae server")
end)

-- use whatever shortcut floats your boat
hl.bind(mainMod .. " + Space", hl.dsp.exec_cmd("vicinae toggle"))

-- blur
hl.layer_rule({
  match = { namespace = "vicinae" },
  name = "vicinae-blur",
  blur = true,
  ignore_alpha = 0,
})

-- disable animation for vicinae only
hl.layer_rule({
  match = { namespace = "vicinae" },
  name = "vicinae-no-animation",
  no_anim = true,
})
```

On first startup, Vicinae will use a lot of CPU in order to populate the file index.

## uwsm - Universal Wayland Session Manager

If you use uwsm to launch and manage Hyprland, use the provided systemd service to start vicinae. Exclude the autostart command above and run `systemctl --user enable --now vicinae.service` instead; vicinae will start immediately and launch on boot moving forward.

## Bind to a custom command

You can easily create a binding to open any vicinae command directly:

```lua
-- ~/.config/hypr/hyprland.lua

hl.bind(mainMod .. " + P", hl.dsp.exec_cmd("vicinae vicinae://launch/clipboard/history"))
```

You can do a lot with this: [learn more about deeplinks](https://docs.vicinae.com/deeplinks).

## Focus window on activation

You may want to focus an application window after vicinae triggers an action related to it.

*For example: using a shortcut action in vicinae that opens a browser tab → Instantly focus the window where the action happened*

You can have this behavior by adding this to your config:

```lua
-- ~/.config/hypr/hyprland.lua

hl.config({
  misc = {
    focus_on_activate = true,
  },
})
```

---

# GNOME Quickstart

This guide explains how to quickly get started with Vicinae on GNOME.

## Install the Vicinae Gnome Extension (Recommended but not required)

The Vicinae Gnome Extension is a companion extension for GNOME that provides the following features:

* Expose **clipboard** events and **window management** APIs through D-Bus
* Blocking specific applications from accessing the clipboard (like password managers)
* Imitate the layer shell protocol to create a detached floating launcher window which closes on focus loss
* Paste clipboard entry to the active window

### Extension Installation

#### **Via [GNOME Extensions Store](https://extensions.gnome.org/)**

1. You can install the extension directly from the [GNOME Extensions](https://extensions.gnome.org/) website or the Extensions Manager App. Check out Vicinae Gnome Extension

#### **Manual Installation**

1. Download the `.shell-extension.zip` from the [latest release](https://github.com/dagimg-dot/vicinae-gnome-extension/releases/latest)
2. Install using: `gnome-extensions install --force <filename>`
3. Restart GNOME Shell or log out/in
4. Enable the extension in GNOME Extensions app

## Start the Vicinae server

### Systemd

On GNOME, the best way to launch the Vicinae server is to enable the systemd user service:

```bash
systemctl --user enable vicinae --now
```

This will start the Vicinae server immediately and make sure it is started when a new GNOME session is started.

To view the server logs:

```bash
journalctl --user -u vicinae
```

### GNOME Startup Applications

An alternative to the systemd service is to use the GNOME Startup Applications in the [Tweaks](https://github.com/GNOME/gnome-tweaks) application which you can get from your software center.

Just select the Vicinae application and GNOME should start the server automatically when a new session opens.

![GNOME Startup Applications](https://docs.vicinae.com/gnome/gnome-tweaks.png)

## Create keyboard shortcuts

### Toggle the window

To create a shortcut that toggles the Vicinae window on a specific keystroke, head to the GNOME keyboard settings and add a custom shortcut for the Vicinae application:

![Create a shortcut to toggle Vicinae on GNOME](https://docs.vicinae.com/gnome/create-shortcut.png)

Once configured, you'll be able to toggle the Vicinae window whenever the shortcut is pressed, provided that the Vicinae server is running.

### Open a specific command

You can use [deeplinks](https://docs.vicinae.com/deeplinks) to create a shortcut that directly opens a custom Vicinae command.

Just create a new shortcut that binds to e.g. `vicinae deeplink vicinae://launch/clipboard/history`.

![Create a deeplink shortcut](https://docs.vicinae.com/gnome/create-deeplink-shortcut.png)

---

# KDE Quickstart

This guide explains how to quickly get started with Vicinae on KDE Plasma.

## Start the Vicinae server

### Systemd

On KDE, the best way to launch the Vicinae server is to enable the systemd user service:

```bash
systemctl --user enable vicinae --now
```

This will start the Vicinae server immediately and make sure it is started when a new KDE session is started.

To view the server logs:

```bash
journalctl --user -u vicinae
```

### KDE Autostart

An alternative to the systemd service is to use the KDE autostart feature from the settings. Just select the Vicinae application and KDE should start the server automatically when a new session opens.

## Create keyboard shortcuts

### Toggle the window

To create a shortcut that toggles the Vicinae window on a specific keystroke, head to the KDE keyboard settings and add a custom shortcut for the Vicinae application:

![Create a shortcut to toggle Vicinae on KDE](https://docs.vicinae.com/kde/create-shortcut.png)

Once configured, you'll be able to toggle the Vicinae window whenever the shortcut is pressed, provided that the Vicinae server is running.

### Open a specific command

You can use [deeplinks](https://docs.vicinae.com/deeplinks) to create a shortcut that directly opens a custom Vicinae command.

Just create a new shortcut that binds to e.g. `vicinae vicinae://launch/clipboard/history`.

![Create a deeplink shortcut](https://docs.vicinae.com/kde/create-deeplink-shortcut.png)

## Blur

Since version `v0.19.7`, vicinae implements the [kwin blur wayland protocol](https://wayland.app/protocols/kde-blur#org_kde_kwin_blur) thanks to which it can request blur by itself. KDE's default blur is pretty strong so you might have to decrease opacity quite a bit in order to get the most out of it.

## Troubleshooting

### The vicinae window won't grab focus

It is possible that your focus prevention policy is interfering with the ability of vicinae to grab focus. Make sure it is set to `low`:

![](https://docs.vicinae.com/kde/focus-stealing-prevention.png)

---

# COSMIC Quickstart

This guide explains how to quickly get started with Vicinae on the [COSMIC desktop](https://system76.com/cosmic) by System76.

The COSMIC Desktop is currently in beta and still has a lot of bugs. Make sure to visit the known caveats section below.

## Start the Vicinae server

### Systemd

If you run COSMIC DE from a proper greeter or using `uwsm`, the best way to autostart the server is to use the systemd user service:

```bash
systemctl --user enable vicinae --now
```

This will start the Vicinae server immediately and make sure it is started when a new COSMIC session is started.

To get the server logs:

```bash
journalctl --user -u vicinae
```

### COSMIC Autostart

An alternative to the systemd service is to use the COSMIC autostart feature from the settings. Just select the Vicinae application and COSMIC should start the server automatically when a new session opens.

## Clipboard history

In most Wayland environments, Vicinae relies on the [wlr-data-control](https://wayland.app/protocols/wlr-data-control-unstable-v1) protocol to monitor clipboard changes.

On COSMIC, this protocol is not enabled by default. To enable it, you need to start COSMIC with `COSMIC_DATA_CONTROL_ENABLED=1`.

If starting COSMIC from a greeter, you will need to edit `/usr/share/wayland-sessions/cosmic.desktop` and change the `Exec` key:

```ini
# /usr/share/wayland-sessions/cosmic.desktop
Exec=env COSMIC_DATA_CONTROL_ENABLED=1 /usr/bin/start-cosmic
```

If running directly from the terminal, you should know what to do 😀

## Create keyboard shortcuts

### Toggle the window

To create a shortcut that toggles the Vicinae window on a specific keystroke, head to the COSMIC keyboard settings and add a custom shortcut for the Vicinae application:

![Create a shortcut to toggle Vicinae on COSMIC](https://docs.vicinae.com/cosmic/create-shortcut.png)

Once configured, you'll be able to toggle the Vicinae window whenever the shortcut is pressed, provided that the Vicinae server is running.

### Open a specific command

You can use [deeplinks](https://docs.vicinae.com/deeplinks) to create a shortcut that directly opens a custom Vicinae command.

Just create a new shortcut that binds to e.g. `vicinae vicinae://launch/clipboard/history`.

![Create a deeplink shortcut](https://docs.vicinae.com/cosmic/create-deeplink-shortcut.png)

## Layer shell

Since version v0.15.2, Vicinae no longer uses the layer shell protocol to position the window on COSMIC. This is mainly because the current implementation appears to be broken, as documented by [this upstream issue](https://github.com/pop-os/cosmic-comp/issues/1590).

## Known caveats

* From extensive testing in a VM, it appears that the Vicinae window can randomly stop showing after a lot of toggling although the application logic is not faulty (Vicinae thinks it's being shown on screen but COSMIC doesn't draw anything). This might not occur on bare metal installs.
* COSMIC is beta software and still has a lot of bugs, as most software in this state does. You shouldn't expect everything to work perfectly.

---

# Niri Quickstart

This guide shows the best way to quickly get started with Vicinae on [niri](https://yalter.github.io/niri).

## Main configuration

Add the following to your niri configuration, and you are good to go.

```ini
# ~/.config/niri/config.kdl
spawn-at-startup "vicinae" "server"

# use whatever shortcut floats your boat
Mod+Space repeat=false { spawn "vicinae" "toggle"; }
```

On first startup, Vicinae will use a lot of CPU in order to populate the file
index.

## Bind to a custom command

You can easily create a binding to open any vicinae command directly:

```ini
# ~/.config/niri/config.kdl

Mod+P repeat=false { spawn "vicinae" "vicinae://launch/clipboard/history"; }
```

You can do a lot with this: [learn more about deeplinks](https://docs.vicinae.com/deeplinks).

## Blur

Niri recently got official blur support and through the use of the `ext-background-effect` protocol, vicinae is able to automatically request blur for its surface.

You should not need to add any specific configuration for blur to work.

## Global shortcuts

Vicinae supports global shortcuts through the `ext-hotkey-v1` wayland protocol. You can build niri from [this PR](https://github.com/niri-wm/niri/pull/4145) if you want support.

## Focus window on activation

Common vicinae workflows such as opening a shortcut will spawn a command that may result in opening a new window or tab in an existing application (typically, browsers). vicinae doesn't yet pass a proper [xdg activation token](https://wayland.app/protocols/xdg-activation-v1#xdg_activation_token_v1) to apps it launches, so the compositor may not allow them to steal focus.

A straightforward fix is to enable the following option in your niri config:

```ini
# ~/.config/niri/config.kdl

debug {
	honor-xdg-activation-with-invalid-serial
}
```

---

# Generic Quickstart

Desktop-agnostic quickstart instructions for Vicinae. If there is a dedicated quickstart guide for your desktop environment, use that instead for environment-specific optimizations.

## Start the server

To start the Vicinae server, simply run:

```bash
vicinae server
```

Or as a systemd user service:

```bash
systemctl --user enable --now vicinae.service
```

If running Vicinae through systemd, please ensure you are starting your compositor as a systemd service, for example with `uwsm`. If you don't, some environment variables may not be properly set and launching some apps may not work.

To view the server logs when using systemd:

```bash
journalctl --user -u vicinae
```

Starting the server can take up to a few seconds when doing so for the very first time.

On first startup, Vicinae will use a lot of CPU to populate the file index.

## Control the window

Once the server is started, you can run `vicinae toggle` to toggle the Vicinae window.

For more advanced controls, see the [deeplinks documentation](https://docs.vicinae.com/deeplinks).

Vicinae doesn't support global shortcuts. You are expected to create keyboard shortcuts yourself using your desktop environment's settings.

![Vicinae window](https://docs.vicinae.com/vicinae-window.webp)

---

# FAQ

Answers to commonly asked questions.

## Vicinae is not packaged for my distribution. How should I install it?

Use the [script](https://docs.vicinae.com/install/linux#install-script) to install the AppImage version, which should work fine on most systems. Don't forget to follow the quickstart guide for your environment once you are done installing.

Do **not** install the AppImage directly.

## How to set a keyboard shortcut to open vicinae?

Vicinae doesn't support global shortcuts at the moment. You should use whatever is the preferred way to set global shortcuts for your environment. If there is a quickstart guide for your environment, this is probably explained there.

## How to set a keyboard shortcut to open a specific command?

You can use [deeplinks](https://docs.vicinae.com/deeplinks) like so:

```bash
vicinae vicinae://launch/clipboard/history
```

How you bind this to a proper keyboard shortcut is different in every environment. Please refer to your desktop environment's documentation.

## How to focus the app window instead of opening a new one?

You can change the default action that is executed for a given application from the settings window. Search for the `Applications` group and the option should be there.

## How to use custom app launcher?

App launchers such as `uwsm` should be detected automatically. If that is not the case, you can specify a custom app launcher in the settings.

## Some of my apps do not launch or are in a weird state

In 99% of cases this is an environment variable issue. See item below.

## Vicinae doesn't pass X environment variable to my apps

Apps launched by vicinae inherit from the parent's environment without any modification. This probably means the environment variable that is missing is not properly injected in vicinae's environment when started. If using the systemd user service, you need to make sure the service is started with the right set of environment variables.

## How to center the launcher window

If you have centering issues, you are probably on Gnome Wayland. The window should be explicitly centered using a tool such as Gnome Tweaks, or you can try the command below:

```bash
gsettings set org.gnome.mutter center-new-windows true
```

## How to blur the launcher window

Blur needs to be supported by your compositor. In such case, you should have a way to add a rule that will apply blur to the vicinae window. The class or scope you need is `vicinae`.

This documentation contains quickstart guides for every major compositor. If blur can be done, be it natively or through some kind of extension, it is likely documented on these pages.

## How to apply scaling

It is possible to enable window scaling for Vicinae by setting the `QT_SCALE_FACTOR` environment variable to an appropriate value:

```bash
QT_SCALE_FACTOR=1.5 vicinae server
```

It is not recommended to set this value globally as it will force scaling for every QT app. If you need desktop-wide scaling you probably want your Wayland compositor to handle this for you. Only use this if you only need the Vicinae window to scale up or down.

## Scrolling is too fast/slow

You can override the `QT_QUICK_FLICKABLE_WHEEL_DECELERATION` environment variable and set it to a lower value (e.g `5000`) to increase scrolling velocity.

```bash
QT_QUICK_FLICKABLE_WHEEL_DECELERATION=5000 vicinae server
```

Starting with v0.20.4, vicinae sets this value to a slightly lower default if the environment variable is not specified.

## How to fix: "extension manager is not running" ?

This likely means you don't have [nodejs](https://nodejs.org) installed on your system, which is required if you want to run third-party extensions.

You should install a recent enough version of node (>= 20) however you like and make sure the `node` binary is in your `PATH`.

Most of the packages distributing vicinae do list `nodejs` as an optional dependency, but maybe the particular one you used doesn't. In that case you are encouraged to reach out to the maintainer of that package.

## How can I extend vicinae?

Three main ways, from least to most customizable:

* [dmenu mode](https://docs.vicinae.com/dmenu)
* [script commands](https://docs.vicinae.com/scripts/getting-started)
* [Typescript SDK](https://docs.vicinae.com/extensions/introduction)

## How to set which terminal to use to launch terminal apps

Since version v0.20.8 vicinae implements the [xdg-terminal-exec spec](https://gitlab.freedesktop.org/terminal-wg/specifications/-/blob/db771e7d8d8461083bf56fb7842b3ee6187ad88c/proposals/xdg-terminal-exec.md)
so you should set your default terminal in `~/.config/xdg-terminals.list`:

```ini {{ title: "~/.config/xdg-terminals.list" }}
kitty.desktop
```

The name of the entry must match the name of the desktop file. You can get it from the vicinae root search by using the "Copy App ID" action on an application entry.

## How to force the vicinae window to show in fullscreen mode?

This usually happens on niri where the `top` layer shell layer is displayed behind fullscreen applications.

You can fix this by changing the layer shell layer to `overlay` in the configuration file (see `vicinae config default`)

vicinae uses `top` instead of `overlay` for various reasons. On some environments, some IME popups end up being shown behind the vicinae window if it's
set to overlay.

If this happens in an environment where layer shell is not a thing, then it's probably another issue.

## Emojis do not load

This is a [known issue](https://github.com/vicinaehq/vicinae/issues/304) when using the AppImage build (typically through the script installation). The TLDR is that QT does not recognize some fonts as emoji fonts. A fix is to try installing another emoji font and see if vicinae automatically picks it up. More complicated workarounds are also discussed in the previously mentionned issue.

## How to deal with read-only configuration?

Vicinae expects the main `settings.json` file to be readable AND writable since it will write configuration changes to it when things are edited from the GUI.

For now, the only solution is to use the `imports` key in this file to import your read-only config from there.

See the [configuration](https://docs.vicinae.com/config) page.

## How to clear navigation queue/state when the window is closed?

There is an option called `pop_to_root_on_close` you can configure that does exactly this.

## How to disable the main window animation?

vicinae doesn't play any animation when showing or hiding its window, this is probably your compositor's doing.

## Raycast-like native AI integration when?

This is currently in development.

## vicinae's memory usage is too high

[top/htop/btop is not a correct way to measure memory usage](https://sw.kovidgoyal.net/kitty/faq/#i-opened-and-closed-a-lot-of-windows-tabs-and-top-shows-kitty-s-memory-usage-is-very-high).

If you think you have found a real memory leak, try to confirm it using [heaptrack](https://apps.kde.org/heaptrack/) or `valgrind` before reporting it as a bug.

When vicinae is run as a systemd service, some system monitors will include the memory consumption of apps launched with vicinae to its own independant memory usage.

---

# Nixos

Vicinae is available as a Nix flake but can also be run without installing. You can use the binaries of the Nix package or enable the systemd service provided by the home-manager module.

## Run Vicinae without installing

You can test the app directly by using a nix shell

```bash
nix shell github:vicinaehq/vicinae
```

## Home Manager module

If you don’t want to compile Vicinae yourself, make sure to enable [Cachix](https://docs.vicinae.com/nixos#cachix)

```nix {{ title: 'flake.nix' }}
{
  inputs = {
    # ...
    vicinae.url = "github:vicinaehq/vicinae";
  };
  outputs = {
    nixpkgs,
    home-manager,
    vicinae,
    ...
  }: {
    nixosConfigurations."..." = nixpkgs.lib.nixosSystem {
      system = "<system>"; # e.g., x86_64-linux
      modules = [
        # ... your other configuration modules ...
        vicinae.nixosModules.default
      ];
    };

    homeConfigurations."..." = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages."<system>"; # e.g. x86_64-linux
      modules = [vicinae.homeManagerModules.default];
    };
  };
}
```

```nix {{ title: 'home.nix' }}
{
  # ...

  programs.vicinae = {
    enable = true; # default: false
    systemd = {
      enable = true; # default: false
      autoStart = true; # default: true (if systemd.enable is true)
      environment = {
        USE_LAYER_SHELL = 1;
      };
    };
  };
}
```

## Cachix

If you want to use the cache do not add `inputs.nixpkgs.follows = "nixpkgs";` to your flake! This will make the cache miss.

The Vicinae flake is **not** built by Hydra, so it is not cached in cache.nixos.org, like the rest of Nixpkgs.
Instead of requiring you to build Vicinae every time it updates, we provide a Cachix cache that you can add to your Nix configuration.

```nix {{ title: 'nix.conf or flake.nix' }}
extra-substituters = [ "https://vicinae.cachix.org" ];
extra-trusted-public-keys = [ "vicinae.cachix.org-1:1kDrfienkGHPYbkpNj1mWTr7Fm1+zcenzgTizIcI3oc=" ];
```

Alternatively you can use the vicinae package from nixpkgs which is built by Hydra, but may be out of date:

```nix {{ title: 'home.nix' }}
{ pkgs, ... }:
{
  programs.vicinae = {
    package = pkgs.vicinae;
  };
}
```

## Configuring with Home Manager

You can configure Vicinae using Home Manager options. Here is an example configuration:

```nix {{ title: 'flake.nix' }}
inputs.vicinae-extensions = {
  url = "github:vicinaehq/extensions";
  inputs.nixpkgs.follows = "nixpkgs";
};
```

```nix {{ title: 'home.nix' }}
programs.vicinae = {
  enable = true;
  systemd = {
    enable = true;
    autoStart = true; # default: true (if systemd.enable is true)
    environment = {
      USE_LAYER_SHELL = 1;
    };
  };
  settings = {
    close_on_focus_loss = true;
    consider_preedit = true;
    pop_to_root_on_close = true;
    favicon_service = "twenty";
    search_files_in_root = true;
    font = {
      normal = {
        size = 12;
        family = "Maple Nerd Font";
      };
    };
    theme = {
      light = {
        name = "vicinae-light";
        icon_theme = "default";
      };
      dark = {
        name = "vicinae-dark";
        icon_theme = "default";
      };
    };
    launcher_window = {
      opacity = 0.98;
    };
  };
  extensions = with inputs.vicinae-extensions.packages.${pkgs.stdenv.hostPlatform.system}; [
     bluetooth
     nix
     power-profile
    # Extension names can be found in the link below, it's just the folder names
  ];
};
```

[Extension names](https://github.com/vicinaehq/extensions/tree/main/extensions)

### Configuring Extensions

To configure extensions with options declaratively, add their configuration as such:

```nix {{ title: 'home.nix' }}
{
#...
  programs.vicinae.settings = {
    providers = {
       # Notice name difference. If declaring install and not installing manually, the name is different
      "@knoopx/nix-0" = {
        preferences = {
          # Declaring Secrets to a public repo is not good. See section below for secrets management
          githubToken = "TOKEN HERE";
        };
      };
    };
  };
}
```

This will vary depending on the fields that each extension expects. This is not limited to Vicinae extensions, but also works for any other "entrypoint."
So Raycast should also be configurable. View the "package.json" for your desired extension to see the options.\
When installing the extension via nix, extension name will be somethint like @author/ext-id, in the provided example,
it's **@knoopx**/**nix-0**.\
To get that name, you can first install the extension either via the home-manager option or vicinae store, then go to the
installed extension menu, open the actions menu (default to ctrl+k) and copy author and ID.

### Declaratively Managing Secrets with sops-nix

This example assumes that you are familiar with secret management and template management through [sops-nix](https://github.com/Mic92/sops-nix).

In your sops secrets file, add the secrets you want to use in Vicinae.

```yaml {{ title: 'secrets.sops.yaml' }}
github: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

We're going to use sops-nix's [template feature](https://github.com/Mic92/sops-nix#templates) in this example.
Templates allow you to generate configuration files dynamically, in Nix, while still keeping the actual secret values encrypted and out of your Nix store.
You can define individual secrets in your sops file and compose them into structured files using placeholders like `config.sops.placeholder.<secret-name>`.
At activation time, sops-nix renders the template with the decrypted secret values and writes the final file securely to disk.
As an additional benefit to this approach, you can still use the secrets elsewhere without needing to declare them multiple times in your sops secrets file.

In either your `home.nix` or your `configuration.nix` add your sops-nix configuration:

```nix {{ title: 'home.nix or configuration.nix' }}
{ config, ... }:
{
#...
  sops = {
    secrets = {
      github = { };
      # ... - you can add more secrets if needed
    };
    templates = {
      "vicinae-secrets.json" = {  # wrapped in "quotes" because it contains a dot
        owner = "your-username";  # if you are using `home-manager`, you can omit this
        content = builtins.toJSON {
          providers = {
            "@knoopx/nix" = {  # wrapped in "quotes" because it contains a `@` and a slash
              preferences = {
                githubToken = config.sops.placeholder.github; 
              };
            };
          };
        };
      };
    };
  };
}
```

Finally, add the sops-nix template file to Vicinae's settings as an import:

```nix {{ title: 'home.nix' }}
{
  programs.vicinae.settings = {
    # NOTE: If you have sops configured in your home.nix, it will be config.sops...
    # otherwise, depending on how your nix is configured, it may be nixosConfig.sops...
    imports = [nixosConfig.sops.templates."vicinae-secrets.json".path];
  };
}
```

the `theme.name` option can be set to any of the themes that come with Vicinae or a custom theme you have installed. See [the Github](https://github.com/vicinaehq/vicinae/tree/main/extra/themes) for more information on default theme names.

---

## Manual

# Configuring Vicinae

Vicinae can be configured using either the GUI or its configuration file. This document presents a brief overview of how configuration works in vicinae.

## GUI Configuration

Vicinae is intended to be fully customizable using the GUI.

There are two main ways to do so:

* Through built-in commands, which may write to the configuration in some circumstances (e.g "Set Theme" command)
* Through the dedicated settings window, which can be opened using the `ctrl-'` keybind or by activating the "Open Settings" built-in command

More intricate settings are only configurable by editing the config file directly, more on that below.

![config](https://docs.vicinae.com/extension-settings.webp)

Extension configuration using the settings window

## Configuration file

All the configurable vicinae settings are serialized in JSONC format (JSON with comments).

Vicinae starts by loading its default configuration, which can be obtained by running the following command:

```bash
vicinae config default
```

Then, the user config file (located at `~/.config/vicinae/settings.json` by default) is read and merged with the default configuration file, overriding any default value.

This user config file needs to be readable **and** writable as most configuration changes made through the GUI will be written to it. If you're dealing with a read-only config , the recommended approach is to use imports as described below.

You can point vicinae to a different user config by passing the --config option to `vicinae server`.

### Config imports

It is possible to split up configuration by importing other config files from the main user config file.

To do so, you simply need to add the files to import to the `imports` array. Files imported in this way are merged before the main user configuration file is considered and are never touched by vicinae directly,
allowing them to be freely formatted and annotated with custom comments.

```json {{ title: '~/.config/vicinae/settings.json' }}
{
	"imports": [
		"base_config.json",
		"keybinds.json"
	],

	// remaining configuration...
}
```

Imported files are merged with the default config **before** the main user configuration file, which means that value present in the user configuration file will always override those that were imported.

### Config documentation

All config options are thoroughly documented in the default configuration file.

### Config exclusions

Extension preferences of type 'password' are not written to the config file because they are treated as sensitive data.
They are stored in the internal sqlite database instead, which will become fully encryptable in the future.

## Migration from v0.16.X to v0.17.X

The overhaul of the configuration system is a huge breaking change: users will need to redo their configuration, either by migrating their old file to the new format by hand or simply by reconfiguring using the GUI.

Provider data (preferences, aliases, etc...) went from being stored in the internal database to being stored in the config file, so there is no easy way to migrate them over. Just use the GUI and let it write the values to the file for you.

The file at `~/.config/vicinae/vicinae.json` is no longer read by vicinae and can be removed, superseded by the `~/.config/vicinae/settings.json` file.

---

# Global keyboard shortcuts

If your environment supports it, Vicinae allows you to assign global keyboard shortcuts to open the launcher window or any other command.&#x20;

| Name | Supported | Comment |
|------|-----------|---------|
| X11 | Yes |  |
| Hyprland | [Pull request](https://github.com/hyprwm/Hyprland/pull/15010) | Through [ext-hotkey-v1](https://github.com/vicinaehq/vicinae-wayland-protocols/tree/main/staging/ext-hotkey), our proposed Wayland protocol |
| Niri | [Pull request](https://github.com/niri-wm/niri/pull/4145) | Through [ext-hotkey-v1](https://github.com/vicinaehq/vicinae-wayland-protocols/tree/main/staging/ext-hotkey), our proposed Wayland protocol |
| Other Wayland | - | Only if [ext-hotkey-v1](https://github.com/vicinaehq/vicinae-wayland-protocols/tree/main/staging/ext-hotkey) is implemented by the compositor |

## Set global shortcuts

Just open the settings (ctrl+comma or use the dedicated command) and every command listed will have a shortcut field that you can click to assign a new shortcut. If there is none, it means you environment doesn't support global shortcuts, as per the table above.

You can also go to the "General Settings" tab to change the global shortcut to use to toggle the window.

![](https://docs.vicinae.com/screenshots/global-shortcuts.png)

---

# Telemetry

vicinae collects basic telemetry in order to help improving the software. This page details what is collected and why. Users can opt-out at anytime by changing a single config item.&#x20;

## Telemetry breakdown

### System info

vicinae collects basic system information when starting up the daemon. Here is a typical payload sent to the vicinae servers:

```jsonc
 {
   "userId": "user-344a37bd-2d65-49ad-9a2f-27769334f64e", // tied to vicinae installation, not derived from machine-id
   "desktops": [
      "niri"
   ],
   "vicinaeVersion": "v0.20.5",
   "displayProtocol": "wayland",
   "architecture": "x86_64",
   "operatingSystem": "linux",
   "buildProvenance": "local",
   "locale": "en_US", // some vicinae features are affected by localization
   "screens": [
      {
         "resolution": {
            "width": 1920,
            "height": 1080
         },
         "scale": 1
      }
   ],
   "chassisType": "desktop",
   "kernelVersion": "6.16.7-gentoo",
   "productId": "gentoo",
   "productVersion": "2.18"
}
```

* We only send information that can help us make better decisions for development or testing.
* We don't send personally identifiable information other than the `userId`: it is unique to vicinae and does *not* use your machine ID. It cannot be used to track you outside of vicinae. We mostly use this to count unique daily active users and version upgrade rates overtime.

vicinae will only send this information once every 24 hours. This is so that we can count how many daily active users we have.

## Disable telemetry

Telemetry is *opt-out* by default. It can be turned off in one of two ways:

* Turn it off from the "general" settings tab
* Edit the `telemetry` object in your [configuration](https://docs.vicinae.com/config)

Please consider leaving telemetry on! It's as non intrusive as possible and it is helping us to make the software better.

## Open data

Aggregated usage data is publicly available [here](https://vicinae.com/open-data).

## GDPR

### Legal grounding

For users based in EU member states: processing is based on legitimate interest under [Article 6(1)(f)](https://gdpr-info.eu/art-6-gdpr/) of GDPR. This is compatible with opt-out telemetry.

### Retention period

1 year.

### Data removal

Since the vicinae server stores an identifier tied to your vicinae installation (and nothing else), it can be used to identify your specific installation across several requests.

You can request the immediate and permanent removal of this data by using the following command:

```bash
vicinae "vicinae://launch/core/forget-telemetry"
```

This will contact the vicinae server one last time to instruct it to delete the data and will automatically turn off telemetry.

---

# dmenu Mode

Vicinae supports a special "dmenu" mode that can be used to generate a list view from a newline-delimited list of entries passed through standard input. It is named in reference to the popular `dmenu` unix program.

This is useful in order to quickly create simpler menus. If you are looking to build more complex menus, you should look into making your own [extension](https://docs.vicinae.com/extensions/introduction).

## Usage

To use dmenu mode, you need to use the `vicinae dmenu` subcommand:

```bash {{ title: 'piped' }}
echo -e 'option 1\noption 2\noption 3\n' | vicinae dmenu --placeholder "Select option"
```

```bash {{ title: 'from file' }}
vicinae dmenu --placeholder "Select option" < options.txt
```

```bash {{ title: 'from stdin' }}
$> vicinae dmenu --placeholder "Select option"
option 1
option 2
option 3
<C-d>
```

![dmenu list view](https://docs.vicinae.com/dmenu.png)

You can get a full list of available options with `vicinae dmenu --help`.

## Quick look

Since version **0.16.3**, dmenu mode supports a quick look feature when absolute file paths are used as inputs.

This enables quick file searches or even simple wallpaper pickers.

```bash
# a simple wallpaper picker
swww img $(find ~/Pictures/walls -type f | vicinae dmenu -p 'Pick a wallpaper...')

# a quick way to browse some files (10,000+ files can become a bit laggy)
xdg-open $(find ~/Desktop/invoices -name '*.pdf' | vicinae dmenu -p 'Select invoice...')
```

If quick look is not desired, it is possible to fully turn it off by passing the `--no-quick-look` flag.

![dmenu quick look](https://docs.vicinae.com/dmenu/quick-look.png)

---

# Snippets

Snippets are a way to store reusable pieces of text that can be parametrized using dynamic placeholders and pasted wherever you need them. Most importantly, snippets can be *universally* expanded if a keyword is specified.

![](https://docs.vicinae.com/snippet-demo.gif)

## Get started with snippets

In order to create your first snippet, just search for the [Create Snippet](vicinae://launch/snippets/create) command.

* The title is used to index your snippet for search, when browsing them using the [Manage Snippets](vicinae://launch/snippets/manage) command.
* The content of the snippet is expressed as plain text. You can use curly brace delimited dynamic placeholders to introduce programmatic elements to your snippet. More on that below.
* You can optionally specify a keyword. When this keyword is typed *anywhere* (not only in the vicinae window) it will automatically expand to the contents of the snippet in place. If a keyword is not specified, the only way to use the snippet is to copy it to clipboard from the manage snippets command.
* If a keyword is specified, you can restrict the expansion of that snippet to specific application windows.

![](https://docs.vicinae.com/create-snippet.gif)

## Keyword expansion

### Trigger expansion

If you filled in the `keyword` field while creating your snippet, then you can expand it by just typing that keyword anywhere (not only in the vicinae window).

### Undo expansion

Since snippet text injection is carried by a clipboard paste, the preferred way to undo a snippet is to use the mechanism provided by the current app in order to undo the last action (here, a clipboard paste). Most of the time, a single `Ctrl-Z` works.

For shorter snippets or in apps that do not have a designated way to undo a clipboard paste, you can just press `ESC` to undo the expansion using vicinae's builtin undo mechanism. Unlike native undo, this will also write the initial keyword back.

Undoing long snippets can take a long time as undo is implemented by sending a series of backspaces that need to be sent at a fixed interval (and, may not even be interpreted properly in some apps).

![](https://docs.vicinae.com/snippet-undo.gif)

## Dynamic placeholders

One of the most appealing features of snippets is that they can expand dynamic content. They can take named arguments, execute shell code, copy current clipboard text and much more. As shown in the video above, you can get the list of available placeholders simply by typing `{` and autocomplete from there.

A dynamic placeholder always follows the syntax: `{<name> [...<key>="<value>"]}`.

Below we discuss the most important placeholders and how they work:

### Shell code

You can run shell code inside your snippet using a `{shell}` placeholder. This placeholder will expand to the full output of the command (stdout only):

```
Hi {name}, today is {shell code="date"}
```

Note that all shell placeholders in your snippet are run concurrently, and each has an execution budget of 2s. If a shell placeholder takes too long or hangs, it is killed and expands to nothing. Generally it is recommended that you only execute short commands. If you want to run longer scripts you are probably looking for [script commands](https://docs.vicinae.com/scripts/getting-started).

### Arguments

Similarly to [shortcuts](https://docs.vicinae.com/shortcuts) you can specify named arguments that will need to be explicitly entered by the user before expanding the snippet.

You just need to use the `{argument}` placeholder like so:

```
{argument name="my_arg"}
```

You can also use the short form of it, which works as long as it doesn't conflict with any other named placeholder:

```
# internally converts to {argument name="my_arg"}
{my_arg}
```

Arguments are only prompted when expanding a snippet from the [Manage Snippets](vicinae://launch/snippets/manage) command. When expanded from a keyword, arguments are silently replaced by the empty string.

### Cursor

Use `{cursor}` in your snippet text so that your cursor will be placed at this exact location after expansion happens.

This only matters if you are expanding the snippet from a keyword, as doing it from the launcher will directly copy the expanded content to your clipboard without injecting any input.

For obvious reasons, you cannot use more than one cursor placeholder in the same snippet.

Cursor placement is implemented by injecting "right key" keystrokes. If the app you are expanding your snippet in doesn't understand these, cursor placement may not fully work.

Avoid placing a `{cursor}` placeholder to the left of a big expansion, as it will make vicinae send a long serie of inputs in order to move the cursor back to the left. This is slow and can't really be sped up in any meaningful way.

### Clipboard text

`{clipboard}` expands to the text content present in the clipboard, if any.

If the clipboard offers no text content (an image is copied) then it expands to nothing.

### Date

You can use the `{date}` placeholder to expand the current date in the specified format:

```
{date format="yyyy-MM-dd hh:mm"}
```

The format is the [QDate format](https://doc.qt.io/qt-6/qdate.html#toString-2).

### UUID

Expands to a UUID v4. Version is not configurable at the moment.

## Security implications

In order to implement snippets and other features relying on input injection, vicinae spawns a binary called `vicinae-input-server` that has two main roles:

* inject input (via /dev/uinput)
* monitor input (by reading /dev/input/eventXX for each keyboard/pointer device)

The code powering the `vicinae-input-server` is kept intentionally minimal in order to minimize the amount of logic a privileged binary like this one executes, making it straightforward to audit.

We give it the required permissions by using kernel capabilities (`setcap`).

## Troubleshooting and known limitations

### vicinae-input-server fails to start

The main reason `vicinae-input-server` can fail to start is if it's not given the elevated privileges it requires.

This is normally done at post install time by the package manager. If you are using a non conventional packaging method, you may need to run `setcap` on the input server manually like so:

```bash
sudo setcap "cap_dac_override+ep" $prefix/libexec/vicinae-input-server
```

Where `$prefix` is the installation prefix of vicinae, typically `/usr`.

On why this is needed, [please read this](#security-implications).

### Keyboard layout

For technical reasons, the snippet system is unable to know what keymap you configured your compositor to use. In most cases, it can be safely inferred from the environment using the primary locale, but it may not always be enough.

You can specify a specific keyboard layout that is to be used for input injection and monitoring in the settings preferences.

### Key delay

On very slow systems or compositors, the delay between each keystroke may not be enough and some may get discarded. You can configure various delays in the snippet extension preferences as well.

### Undoing or moving the cursor takes too long

This is a known issue that unfortunately doesn't have a good fix. This is because these two behaviors rely on injecting input at a given interval so that the app has time to consume them, which can only go so fast.

Typing anything or moving your mouse will automatically cancel any pending injection, so that it doesn't leak to other windows or trigger unexpected behavior.

---

# Clipboard Management

Vicinae fully integrates with your system clipboard and includes a powerful clipboard history module.
In practice, this makes Vicinae a capable standalone clipboard manager as well.
This document explains how it works and outlines its key features.&#x20;

![](https://docs.vicinae.com/screenshots/clipboard-history-gruvbox.webp)

## Environment Support

Clipboard behavior can vary significantly depending on the desktop environment or compositor in use. Below is a table showing which environments Vicinae currently supports.

If you'd like to contribute support for an environment that isn't yet compatible, please [read this guide](https://docs.vicinae.com/contrib/clipboard).

| Name | Supported | Comment |
|------|-----------|---------|
| X11 | ✅ |  |
| KDE Wayland | ✅ | Uses the `wlr-data-control` protocol |
| COSMIC | ✅ | Requires `COSMIC_DATA_CONTROL_ENABLED=1` ([see setup guide](https://docs.vicinae.com/quickstart/cosmic#clipboard-history)) |
| Gnome | ✅ | Using the Vicinae Gnome Extension (See installation [on Gnome Quickstart](https://docs.vicinae.com/quickstart/gnome#install-the-vicinae-gnome-extension-recommended-but-not-required)) |
| Hyprland | ✅ | |
| Sway | ✅ | |
| Niri | ✅ | |
| Other Wayland compositors | - | Works if the compositor implements `wlr-data-control` (most do) |

## Introduction

When launched, Vicinae starts a clipboard server that monitors clipboard activity in the current environment.

You can quickly check whether clipboard management is active by opening the clipboard history command.

If the option shows `Pause clipboard` or `Resume clipboard`, it means a working clipboard server is currently tracking clipboard activity.

If it displays an error instead, your environment may not be supported, or another issue may have occurred. The logs can help you pinpoint the cause.

## Data Storage

The clipboard data is stored in two main places:

* The full selection data (including some alternative offers) is stored inside a directory, optionally encrypted
* The selection metadata is stored inside a specific SQLite database

## How it works

At startup, Vicinae will attempt to spawn a clipboard server that can serve the current environment. What server is activated will depend on what environment you are in.

The duty of the clipboard server is to monitor the system clipboard and notify Vicinae of selection changes, so that they can be pulled in and added to the history.

The indexing logic is handled by the Vicinae clipboard service, which is environment-agnostic. [More details here](https://docs.vicinae.com/contrib/clipboard).

### Preserving selection identity

Vicinae makes a general attempt at trying to preserve most of the selection's "identity" by also storing alternative offers if they are meaningful.

For example, this is what you get in your clipboard after "copying" a file from the Nautilus file manager:

```bash
# wl-paste -l
x-special/gnome-copied-files
application/vnd.portal.filetransfer
application/vnd.portal.files
text/uri-list
text/plain;charset=utf-8
```

This clipboard selection is made of 5 offers, that is, 5 different forms the selection can be requested as.
All the offers may or may not contain readable data; some of them are actually used for protocol purposes.

In this example, `application/vnd.portal.filetransfer` is actually used to [implement proper drag-and-drop behavior](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.FileTransfer.html).

What form is to be pasted to the target application will depend on what the target application is most comfortable with, as it is free to request any form the selection is offered as.

In this case, this is generally `text/uri-list`, which contains a link to the file.

```bash
# wl-paste -t text/uri-list
file:///home/aurelle/wallpapers
```

A typical way to implement a clipboard manager is to use `wl-paste` in watch mode and pipe it to a program that can store and retrieve the data, such as `cliphist`:

```bash
wl-paste --watch cliphist store
```

One major drawback of this approach is that it only preserves what `wl-paste` [deems to be the "best" offer](https://github.com/bugaevc/wl-clipboard/blob/aaa927ee7f7d91bcc25a3b68f60d01005d3b0f7f/src/wl-paste.c#L143), that is, the one that is probably going to satisfy the most applications.

While this is generally good enough, this still strips out potentially valuable information from the selection and can totally break it in some cases.

There is no good way to solve this other than to store the many representations of the data for later use.

For a number of reasons, we can't do it for strictly every offer, as it could significantly bloat the history, but Vicinae tries its best to be smart about it.

There is no general rule about how this is done because this partly depends on the clipboard server implementation, which is environment-specific.

### Better selection indexing

Another advantage of preserving the selection identity is that it allows vicinae to index all text offers, even if they are not used as the primary way to represent the data.

Take an image copied from any chromium browser for instance, this is what you get in your clipboard:

```bash
# wl-paste -l
chromium/x-source-url
image/png
text/html
text/x-moz-url
```

While Vicinae will normally consider the image type to be the primary type of the selection, the selection will still be indexed
against the `chromium/x-source-url` type, which means the selection is searchable using words that may appear in the URL.

## Ignored Selections

A clipboard selection can be completely ignored in any of the following circumstances:

* It contains a `vicinae/concealed` offer (mostly for internal use)
* It contains a special password manager hint offer indicating that the selection is a password. One popular example is `x-kde-passwordManagerHint`.
* It is fully empty (clipboard clear)
* The primary offer (the offer that is used to show the data in the history) is empty.

## Tagging Selections

The clipboard history command allows you to tag selections with custom keywords.
Simply activate the Edit keywords action (defaults to `ctrl+E`) on any selection and enter the desired keywords. These tags make it easier to locate a selection later through search.

## Encryption

By default, the clipboard data is stored on disk unencrypted, but it is possible to opt into using encryption (AES256-GCM) by enabling it in the clipboard extension preferences.
Note that doing so requires the system to provide a working keychain in order to store and retrieve the encryption key.

### Encryption Caveats

The way the clipboard history currently works exposes the following caveats in relation to encryption:

* The selection metadata (mime type, text preview, size...) is never encrypted, as it is stored in an SQLite database and not directly on disk.
* Text content is indexed in an FTS5 SQLite virtual table, which means it's technically retrievable in its unencrypted form.

These two issues would be fixed by "simply" encrypting the SQLite database, but this comes with its own challenges, which is why this is currently not implemented.

## Clear history

You can use the "Remove all" action from the clipboard history command.

It is also possible to automatically clear the history on every startup by enabling the relevant preference in the clipboard extension preferences.

## History size limit

There is currently no limit as to how big the clipboard history can grow.&#x20;
Note that the history view will only display the latest 1,000 entries if no search filter is given.

---

# Window Management

Vicinae fully integrates into the system window manager and allows you to control opened windows.

## Introduction

Vicinae currently supports window listing, focusing and closing on switch windows view:

Further more, it detects opened windows on root search view and allows you to focus them.

## Environment Support

Window management support can vary depending on the desktop environment or compositor in use. Below is a table showing which environments Vicinae currently supports.

| Name | Supported | Comment |
|------|-----------|---------|
| Gnome | ✅ | Using the Vicinae Gnome Extension (See installation [on Gnome Quickstart](https://docs.vicinae.com/quickstart/gnome#install-the-vicinae-gnome-extension-recommended-but-not-required)) |
| Hyprland | ✅ | Using built-in IPC |
| X11 | ✅ | Using XCB |
| KDE Wayland | ✅ | Uses an internal D-Bus KRunner API, very brittle. Help wanted. |
| COSMIC | ❌ | Planned for future implementation |

---

# Calculator

Vicinae is able to integrate with many different calculator backends to provide you with the ability to do maths using natural language from within the launcher.
Most backends support quality of life stuff such as currency or unit conversions.&#x20;

![](https://docs.vicinae.com/calculator-date.webp)

Date conversions using the [SoulverCore](https://github.com/vicinaehq/soulver-cpp) backend.

## Supported backends

Vicinae allows choosing from different calculator backends.

| Name | Default | Comment |
|------|-----------|---------|
| [Qalculate!](https://github.com/Qalculate/libqalculate) | ✅ | Default calculator choice for most Linux software, fully open-source |
| [SoulverCore](https://github.com/soulverteam/SoulverCore) | ❌ | Very powerful, closed-source, see [guide](https://docs.vicinae.com/calculator#soulver-core-backend-installation) |

## Change the calculator backend

You can change the current backend in use from the calculator extension's preferences in the settings.

Note that the backend change will be effective immediately as you type something new in the root search.

![](https://docs.vicinae.com/calculator-backend-settings.webp)

## Calculator history

Vicinae comes with a backend-agnostic clipboard history module that will save every calculation that you have ever made. From there, you can search any past calculation, copy the result or the entire expression, and much more...

You need to copy the result of a calculation for it to be saved in the history.

## SoulverCore backend installation

The [SoulverCore](https://github.com/soulverteam/SoulverCore) backend is distributed as a **closed-source** shared library on Linux systems.

Unlike most other backends, support for SoulverCore is not something that can be enabled at build time. Instead, Vicinae will try to load up a specific shared library on startup and, on success, add the SoulverCore backend to the list of available ones.

All you need to do is follow the instructions present in our [soulver-cpp](https://github.com/vicinaehq/soulver-cpp) repository. If all goes well, the shared library will be made available to Vicinae and SoulverCore should automatically appear as a selectable backend after you restart the Vicinae server.

---

# Shortcuts

This page explains how to create, manage and use application shortcuts from within Vicinae.

## Introduction

Shortcuts are provided as a way to quickly extend the root search with dynamic application shortcuts.
If you are coming from Raycast, this is very close to their "quicklink" feature.

Some use cases include:

* Open an http url such as `https://google.com/search?q={query}` where `{query}` is completed from within the launcher. Typically used for web search tasks.
* Open any system application with a specific URI, for instance to open a VSCode workspace.
* Open a URL or application with the content of the clipboard (if text) provided as its first argument

And much, much more...

![](https://docs.vicinae.com/shortcut-google.webp)

## Create a shortcut

In order to create a shortcut, simply launch the [Create Shortcut](vicinae://launch/shortcut/create) command:

* The name will be used to identify and index the shortcut in the root search
* The icon can be any Vicinae built-in icon, the opening application's icon, or a favicon if the URL field is a web URL.

The URL field doesn't have to be an http URL. It can be anything, such as a file path, arbitrary text...

## Supported applications

As of now, all system applications can be used as shortcut openers.

On systems that use [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/) (all Linux systems), sub-actions are also made available as valid shortcut openers.

Thanks to that, it's easy to create a shortcut that specifically opens in a firefox private window:

![](https://docs.vicinae.com/shortcut-private-window.webp)

## Manage shortcuts

The [Manage Shortcuts](vicinae://launch/shortcut/manage) command lists all your existing shortcuts and allows you to open, edit, duplicate, or remove any shortcut from the list.

The preview shown on the right automatically updates as you start completing the arguments, making testing your shortcut easier.

![](https://docs.vicinae.com/manage-shortcuts.webp)

## Use as fallback command

All shortcuts that have exactly **one argument** are eligible to be selected as a [fallback command](https://docs.vicinae.com/fallback-commands).

An argument is a specific placeholder type that has to be explictly supplied in the search bar.  Automatically expanding placeholders such as `{uuid}` or `{clipboard}` **do not** count as arguments.

---

# File Search

Vicinae integrates with your filesystem in order to provide you with snappy file search. This page describes how it works and how to get the most out of it.

![Search Files](https://docs.vicinae.com/search-files.webp)

## Environment support

The way Vicinae works with file indexing depends on the environment. Since we are mainly focusing on Linux right now, most of this document refers to the custom file indexer.

| Name | Supported | Comment |
|------|-----------|---------|
| Linux | ✅ | Custom file indexer implementation |
| MacOS | TBD | Will integrate with Spotlight, no direct indexing |

## Initial indexing

On environments making use of the custom file indexer implementation, Vicinae will start a **full scan** on first startup.

A full scan will go through every single file and directory present at the configured search locations and index them. By default, we only index the contents of the home directory.

It is expected for Vicinae to use a lot of CPU during initial file indexing, as the priority is to build the base index as fast as possible.
Subsequent indexing is done incrementally and is way less CPU intensive.

You may be able to start searching for files as the indexing goes through. If nothing shows up after a few minutes, then something probably went wrong and you should let us know.

If the Vicinae server is interrupted during file indexing, it is smart enough to know about it and start a new scan on next startup. Note, however, that the index will have to be fully rebuilt from scratch.

## Search paths

By default we only search files and folders that are under the current user's home directory.

You can change the list of searched locations from the file search extension settings:

Adding new search locations might trigger new indexing tasks immediately.

![Edit search paths from settings](https://docs.vicinae.com/search-locations.webp)

## Special indexing rules

Currently, we have a few special indexing rules in place, mostly as a way to speed up indexing (the defaults may change soon):

* dot files and dot folders are not indexed (will be made configurable)
* `.gitignore` files are read and considered as they would normally be in a git repository (although we don't use proper gitignore patterns so some complicated ones may not work)

We have an ongoing [GitHub discussion thread](https://github.com/vicinaehq/vicinae/discussions/190) about this.

## Search files

You can search files in one of two ways:

* From the root search, only if the relevant option has been explictly enabled in the main Vicinae settings. Root file search is performed asynchronously so you should expect a slight delay before file results show up.
* Using the dedicated [Search Files](vicinae://launch/file/search) command, which provides a nice preview of the file's content and generally more actions.

## Watcher (Experimental)

You can add paths to 'Watcher paths' in the settings to watch for real-time changes with [e-dant/watcher](https://github.com/e-dant/watcher).

There are a number of caveats:

* There is no way to watch 'unwanted' directories like `node_modules` and hidden paths
* It requires an inotify instance for every subdirectory, and you can hit the system limit. You can increase this limit by:
  * Writing a larger number to `/proc/sys/fs/inotify/max_user_watches`
  * Setting it in /etc/sysctl.conf:\
    `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`

---

# Browser Extension

Vicinae can connect to your browser to search, focus and delete your browser tabs, alongside other cool integrations. This page describes how to get started and highlights the most useful features.

![](https://docs.vicinae.com/browser-tabs.png)
*Tabs are searchable directly from root or from within the dedicated command*

## Installation

### Prerequisites

If you installed vicinae from the AUR, using the script (as root) or from source, the prerequisites below should automatically be handled for you.
When possible, these installation mediums automatically generate and install the required native host manifests on your system.

Known exceptions are:

* AppImage install that was not performed as root
* Any other esoteric packaging method that does not use the cmake install target

Your browser must be able to find a `com.vicinae.vicinae.json` manifest whose `path` references a valid `vicinae-browser-link` binary. Common system-wide locations on Linux are:

* Chromium: `/etc/chromium/native-messaging-hosts/`
* Google Chrome: `/etc/opt/chrome/native-messaging-hosts/`
* Firefox: `/usr/lib/mozilla/native-messaging-hosts/`

If you installed the browser extension manually, make sure the manifest allows the ID of your installed extension.

#### NixOS and Home Manager

When using the Vicinae Home Manager module, native messaging is configured automatically for Google Chrome or Firefox that (only browsers managed by Home Manager):

* `programs.google-chrome.enable = true`
* `programs.firefox.enable = true`

The corresponding `programs.vicinae.enableChromeIntegration` and `programs.vicinae.enableFirefoxIntegration` options are enabled by default.

For another Chromium-based browser managed by Home Manager, use the browser's `nativeMessagingHosts` option. For example, with Brave:

```nix
{ config, ... }:
{
  programs.brave = {
    enable = true;
    nativeMessagingHosts = [ config.programs.vicinae.package ];
  };
}
```

If the browser is not managed by Home Manager, link the manifest into its per-user native messaging directory instead. For example:

```nix
{ config, ... }:
let
  vicinaePackage = config.programs.vicinae.package;
in
{
  home.file.".config/brave/NativeMessagingHosts/com.vicinae.vicinae.json".source =
    "${vicinaePackage}/etc/chromium/native-messaging-hosts/com.vicinae.vicinae.json";
}
```

For a system-wide NixOS setup without Home Manager, declare the manifest at the path expected by the browser. For example, with Chromium:

```nix
{ inputs, pkgs, ... }:
let
  vicinaePackage = inputs.vicinae.packages.${pkgs.stdenv.hostPlatform.system}.default;
in
{
  environment.etc."chromium/native-messaging-hosts/com.vicinae.vicinae.json".source =
    "${vicinaePackage}/etc/chromium/native-messaging-hosts/com.vicinae.vicinae.json";
}
```

For Firefox enabled through NixOS, add the package to `programs.firefox.nativeMessagingHosts.packages`.

### From web extension stores

The most straightforward way to get the extension is to download it directly from the official extension stores:

* Chromium based browsers: [chrome extension store](https://chromewebstore.google.com/detail/vicinae-integration/kcmipingpfbohfjckomimmahknoddnke)
* Firefox based browsers: [mozilla extension store](https://addons.mozilla.org/en-US/firefox/addon/vicinae/versions/)

> \[!IMPORTANT]
> On Firefox based browsers, by default, the Vicinae extension won't have 'Run on Sites with restrictions' permisson.  That can interfere with, as an example, the Bitwarden password manager Firefox extension's auto-fill function on sites flagged for 'restricted' permissions, like reddit.  If you would like to allow that:
>
> * navigate to 'about:addons' and click on the three dot menu to the right of Vicinae
> * select 'Manage', select 'Allow' to the right of 'Run on Sites with restrictions', close and reopen your browser.
>
> [More information on Mozilla's restricted domain policy here.](https://support.mozilla.org/en-US/kb/quarantined-domains?as=u\&utm_source=inproduct)

### Manual

Go through the instructions in this [README](https://github.com/vicinaehq/vicinae/blob/main/src/browser-extension/README.md) file to install the browser extension and its requirements. This documentation is currently rudimentary and mostly intended for advanced users. Installing from the official browser stores will be the user friendly way to set this up.

## How it works (simplified)

Vicinae makes use of the [native messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) browser API to spawn a special worker process when the browser extension is started that is responsible for mediating communication between the browser extension and the vicinae server. From there both exchange messages as needed, to notify changes (e.g browser tab changes) or request actions (e.g focus or close a tab).

## Noteworthy features

### Create shortcut from active tab

A common use case for the browser integration is to create a [Vicinae shortcut](https://docs.vicinae.com/shortcuts) from the currently active tab.

Using the `Create Shortcut from Active Tab` command, you can do this in two steps without having to manually open the `Create Shortcut` command and copy the link.

### Transform tab to shortcut

Similar to the feature described above, but through an action made available to each searchable tab. Pressing `shift+return` will automatically switch to the `Create Shortcut` view for you.

## Privacy policy

All data stays local. Everything is [open source](https://github.com/vicinaehq/vicinae), and can be fully audited.

---

# Fallback Commands

This page explains how to deal with fallback commands in Vicinae.

## Introduction

Fallback commands are commands that will be shown at the very bottom of the root search when no better matches are available for the current query.

Unlike regular commands, fallback commands will directly work with the provided query as their input.
A fallback command  is usually either a launcher command (view or no view) or an application shortcut.

![](https://docs.vicinae.com/fallback-commands-root.webp)

## Fallback command behaviour

A fallback command will act slightly differently depending on its item type:

* A *view* command will be launched and have its search text immediately set to the fallback text. If the view type does not support search, no completion happens.
* A shortcut or *no-view* command will be launched with the search query passed as its first argument

## Set fallback commands

You can use the [Manage fallback commands](vicinae://launch/vicinae/manage-fallback) command to select what commands or shortcuts are eligible to be fallback commands.

You may have noticed that not all commands and shortcuts appear in this list: fallback eligibility follows these rules:

* All *view* commands exported by third-party extensions can be selected as fallback
* Shortcuts or *no-view* commands that take exactly one **text** argument (required or optional) can be selected as fallback
* Select built-in commands (such as `Search Files`) can be selected as fallback, but most don't

![](https://docs.vicinae.com/manage-fallback-commands.webp)

---

# Extensions

This page explains how to install and run extensions. If you are looking to build your own extensions or learn more about the extension system, please refer to the [extension section](https://docs.vicinae.com/extensions/introduction) of this documentation.

## Install from Vicinae store

Since version **0.16.0** vicinae now hosts its own extension store. You can access it directly from the main search. The source code for all the published extensions can be found on [GitHub](https://github.com/vicinaehq/extensions).

![](https://docs.vicinae.com/vicinae-store.png)

## Install from source tree

This assumes you have downloaded an extension's source code from somewhere on the Internet (e.g GitHub).

From the extension's source tree, simply run:

```bash
npm install
npm run build
```

After it's built, you should be able to search for commands exported by this extension.
No server restart is required.

## Raycast Extensions

You can install Raycast extensions published to the official Raycast store in one click from within Vicinae:

Launch the [Raycast Store](vicinae://launch/raycast-compat/store) command, search for the extension you are looking for, click on details and then install.

Vicinae will then download the extension from Raycast's servers and install it right away, making it immediately available from the root search.

![](https://docs.vicinae.com/raycast-store-list.webp)

Raycast extension support will vary a lot from one extension to another, due to some of them being specifically built for MacOS. We maintain a [list of all compatible extensions](https://docs.google.com/spreadsheets/d/1GAdVeSaKQxXCVJv2_M5zi-mA1IoHieW_Py-VXmPYpeg), as per our own testing.

## Uninstall extension

You can uninstall an extension from the root search by searching for the "Uninstall Extension" action:

![](https://docs.vicinae.com/uninstall-extension.webp)

---

# Emoji Picker

Vicinae ships with a capable emoji picker out of the box.

![](https://docs.vicinae.com/emoji-picker.webp)

## Use emoji picker

Simply launch the [Search Emojis and Symbols](vicinae://launch/core/search-emojis) command.

From there you can copy, pin or add custom keywords to index a specific emoji.

## Emoji font selection

Currently, Vicinae uses a somewhat hacky method in order to figure out what emoji font should be used.

If Vicinae doesn't pick up the emoji font you would like it to, it is possible to override it by setting the `EMOJI_FONT` environment variable to the font family of your choice.

For instance:

```bash
EMOJI_FONT=Twemoji vicinae server
```

If the family doesn't exist, a warning will be printed out and the regular emoji font selection logic will apply.

---

# Deeplinks

Deeplinks are a mechanism allowing you to control Vicinae using the `vicinae://` url scheme. It allows you to toggle the window visibility, launch a specific command, and much more.

## Using Deeplinks

You can pass Vicinae URLs using the `vicinae` binary directly. For instance, here is how you can toggle the window visibility:

```bash
vicinae vicinae://toggle
```

Assuming the `vicinae` url scheme has been registered system-wide, you can also directly use it with tools such as `xdg-open`:

```bash
xdg-open vicinae://toggle
```

Browsers can also execute custom url schemes, with a few caveats.
If Vicinae is currently running, [clicking this link](vicinae://toggle) should toggle the window.

For security reasons clicking a URL with a custom url scheme on a browser page will only work the first time on most browsers until you refresh the page. This is by design and can't really be worked around cleanly.

## Deeplinks as keyboard shortcuts

Deeplinks are the preferred way to bind keyboard shortcuts using your favorite window manager.

For instance, someone using Hyprland would create this binding to toggle the Vicinae window when `Super + Space` is pressed:

```bash
bind = $mainMod, Space, exec, vicinae vicinae://toggle
```

If you are invoking deeplinks directly, it is recommended to execute them using the `vicinae` binary directly instead of using `xdg-open` or a similar tool, which will perform additional lookups and therefore be slower.

## Launch any entrypoint

To activate the primary action of an entrypoint shown in the root search:

```bash
vicinae://launch/<provider>/<entrypoint>
```

For instance, this is how to open the [clipboard history command](vicinae://launch/clipboard/history) using a deeplink:

```bash
vicinae://launch/clipboard/history
```

You can find the deeplink for any entrypoint listed in the root search by using the "Copy Deeplink" command:

![](https://docs.vicinae.com/deeplink-action.gif)

### Pass fallback text to command

The query parameter `fallbackText` can be used to set a fallback search text when launching the command:

```bash
vicinae 'vicinae://launch/clipboard/history?fallbackText=text'
```

### Toggle deeplink

You can pass `toggle=true` to a deeplink in order to automatically close the window if it's already open, and otherwise open the deeplink like normal. This is generally useful when binding a deeplink to a keybind and wanting toggle behavior.

```bash
vicinae 'vicinae://launch/clipboard/history?toggle=true'
```

## Filter root search by provider

It is possible to restrict search to items that are part of a given provider using the following deeplink:

```bash
vicinae 'vicinae://launch/<provider>'
```

For instance, to only search through power commands:

```
vicinae 'vicinae://launch/power'
```

## Window controls

The following deeplinks can be used to control the window and the navigation:

```bash
vicinae://toggle
vicinae://open
vicinae://open?popToRoot=true
vicinae://close
vicinae://pop_to_root
vicinae://pop_current
```

## Settings controls

Deeplinks are available to control the settings window as well:

```bash
vicinae://settings/open?tab=about
vicinae://settings/close
```

## Set theme

It is possible to change the current theme using the following deeplink:

```bash
vicinae://theme/set/<theme_id>
```

The theme id is the name of the JSON theme file without the extension. For a theme file named `gruvbox.json`, use `gruvbox`.

## Raycast compatibility

In order to remain compatible with Raycast, the `raycast://` scheme can be used interchangeably with `vicinae://`.

---

# Favicon Loading

By default, Vicinae will use favicons to provide rich integration with remote URLs.

![](https://docs.vicinae.com/favicon-loading.webp)

## Favicon provider

By default, we use the [Twenty](https://github.com/twentyhq/favicon) favicon provider to load and then cache favicons.

You can change the provider used to fetch favicons or disable favicon loading entirely from the settings.

---

## Theming

# Getting Started with Theming

Vicinae provides a theming system for customizing the appearance using TOML-based theme files.

The current TOML-based theming system was introduced in v0.15.0, replacing the previous JSON-based format. If you have custom themes from before v0.15.0, you'll need to migrate them to the new format.

## What is a Vicinae Theme?

A Vicinae theme is a configuration file written in [TOML](https://toml.io/en/) that defines colors and metadata for the application's appearance. Themes support inheritance, hot reloading, and advanced color manipulation features.

Vicinae can also integrate with tools like [matugen](https://github.com/InioX/matugen) to automatically generate themes from wallpapers or images, creating cohesive color schemes across your entire system. See the [matugen integration guide](https://docs.vicinae.com/theming/matugen) to learn how to set this up.

## Quick Start

To change your theme, use the built-in theme selector:

1. Open Vicinae's root search
2. Type "Set Theme" and select the command
3. Choose from the available themes

![Theme selector interface](https://docs.vicinae.com/vicinae-set-theme.webp)

Alternatively, you can use the CLI:

```bash
vicinae theme set <theme_id>
```

The theme ID is the filename without the `.toml` extension.

## Creating Your First Theme

Generate a complete theme template with all available options:

```bash
vicinae theme template > ~/.local/share/vicinae/themes/my-new-theme.toml
```

Here's a minimal example:

```toml
[meta]
version = 1
name = "My Custom Theme"
description = "A personalized theme for Vicinae"
variant = "dark"
inherits = "vicinae-dark"

[colors.core]
background = "#1E1E2E"
foreground = "#CDD6F4"
accent = "#89B4FA"
```

## Theme Variants

Themes come in two variants:

* **dark** - For dark mode interfaces (inherits from `vicinae-dark`)
* **light** - For light mode interfaces (inherits from `vicinae-light`)

Every theme automatically inherits from its corresponding base theme (`vicinae-dark` or `vicinae-light`), so you only need to specify the colors you want to change.

## Next Steps

* Learn about [theme file structure](https://docs.vicinae.com/theming/theme-structure) and available color options
* Explore [advanced features](https://docs.vicinae.com/theming/advanced-features) like inheritance and color manipulation
* Discover [CLI tools](https://docs.vicinae.com/theming/cli-tools) for managing and validating themes

---

# Theme Structure

A Vicinae theme file is written in TOML and consists of two main sections: metadata and color definitions.

## File Format

Theme files use the `.toml` extension and follow a structured format. Here's a minimal example:

```toml
[meta]
version = 1
name = "Catppuccin Mocha"
description = "Cozy feeling with color-rich accents."
variant = "dark"
icon = "icons/catppuccin-mocha.png"
inherits = "vicinae-dark"

[colors.core]
background = "#1E1E2E"
foreground = "#CDD6F4"
secondary_background = "#181825"
border = "#313244"
accent = "#89B4FA"

[colors.accents]
blue = "#89B4FA"
green = "#A6E3A1"
magenta = "#F5C2E7"
orange = "#FAB387"
purple = "#CBA6F7"
red = "#F38BA8"
yellow = "#F9E2AF"
cyan = "#94E2D5"
```

## Metadata Section

The `[meta]` table contains information about the theme itself. The following fields are available:

### Required Fields

* **version** - Theme format version (currently `1`)
* **name** - Display name for the theme
* **description** - Brief description of the theme's appearance or style
* **variant** - Either `"dark"` or `"light"`

### Optional Fields

* **icon** - Path to a theme icon
  * Can be an absolute path
  * Can be relative to the theme file's directory
* **inherits** - Parent theme to inherit from (see [Advanced Features](https://docs.vicinae.com/theming/advanced-features))

Every dark theme inherits from `vicinae-dark` at the lowest level, and light themes inherit from `vicinae-light`, even if not explicitly specified.

## Color Tables

Everything under the `[colors]` table expects color values. All subtables and keys are optional - you only need to define the colors you want to customize.

### Common Color Tables

The most commonly used color tables include:

* **colors.core** - Base colors for background, foreground, borders, and accents
* **colors.accents** - Named accent colors (red, green, blue, etc.)
* **colors.input** - Colors specific to input fields
* And many more specialized tables for specific UI components

Use `vicinae theme template` to see all available color tables and keys.

If you need additional color customization options that are not currently available, you can request them as a feature on the [GitHub issue tracker](https://github.com/vicinaehq/vicinae/issues).

## Color Value Formats

Color values can be specified in multiple ways:

### 1. Simple Color Names

Direct color specification using hex codes:

```toml
[colors.core]
background = "#1E1E2E"
foreground = "#CDD6F4"
```

### 2. Color References

Reference other colors defined in the theme:

```toml
[colors.core]
accent = "#89B4FA"

[colors.input]
border_focus = "colors.core.accent"
```

### 3. Complex Color Objects

Use a map for advanced color manipulation (see [Advanced Features](https://docs.vicinae.com/theming/advanced-features)):

```toml
[colors.core]
border = { name = "colors.accents.blue", opacity = 0.5 }
```

## Color Name Formats

Vicinae accepts the following color name formats:

* **#RGB** - Short hex format (e.g., `#FFF`)
* **#RRGGBB** - Standard hex format (e.g., `#FFFFFF`)
* **#AARRGGBB** - Hex with alpha channel (e.g., `#AAFFFFFF`, first byte is opacity)
* **Color reference** - Path to another color (e.g., `colors.accents.red`)
* **Named colors** - General colors like `red`, `green`, `blue`, `transparent` (not recommended for themes)

## Validation

Not all values need to be valid - invalid colors will fallback to the parent theme's value. Warnings for invalid color names are printed in the Vicinae logs. However, certain errors will prevent the theme from loading entirely:

### Fatal Errors

* Missing `meta.name` or `meta.description` fields
* Circular color references (e.g., color A references B, which references A)

If a theme fails to load, an error message will appear in the logs, and the theme won't be available in theme selectors.

## Next Steps

* Learn about [advanced color features](https://docs.vicinae.com/theming/advanced-features) like inheritance and color manipulation
* Explore [CLI tools](https://docs.vicinae.com/theming/cli-tools) for validating and managing themes

---

# Advanced Features

Vicinae's theming system includes features for color manipulation and theme composition.

## Theme Inheritance

Theme inheritance allows you to base a new theme on an existing one and override specific values.

### Basic Inheritance

Here's how to create a custom theme based on an existing one:

```toml
[meta]
name = "My Rosepine Fork"
description = "Rosepine with green accent"
variant = "dark"
inherits = "rose-pine"

[colors.core]
accent = { name = "colors.accents.green", opacity = 0.7 }
```

This theme inherits all colors from `rose-pine` and only overrides the accent color.

### Inheritance Chain

Themes can inherit from other custom themes, creating an inheritance chain. For example:

```
my-theme → rose-pine → vicinae-dark
```

Each theme in the chain can override specific values while preserving everything else.

### Default Inheritance

Even without explicitly setting `inherits`, all themes automatically inherit from base themes:

* Dark themes inherit from `vicinae-dark`
* Light themes inherit from `vicinae-light`

Make sure your theme uses a unique filename (theme ID). If you use the same filename as the theme you're inheriting from, the overridden theme won't be inheritable by other themes.

## Complex Color Values

While simple color names (like `#FFFFFF`) work for most cases, Vicinae supports complex color objects that enable advanced color manipulation.

### Basic Syntax

A complex color value is a map with at least a `name` field:

```toml
[colors.core]
border = { name = "colors.accents.blue" }
```

This is functionally equivalent to:

```toml
[colors.core]
border = "colors.accents.blue"
```

Additional properties can be added for color manipulation.

### Opacity Modification

Change the opacity (alpha channel) of any color:

```toml
[colors.core]
accent = "#89B4FA"
border = { name = "colors.core.accent", opacity = 0.5 }
```

The `opacity` field can be used to modify referenced colors. Alpha can also be specified in hex format (`#AA89B4FA`).

The `opacity` value ranges from `0.0` (fully transparent) to `1.0` (fully opaque).

### Lightness Modification

Adjust the lightness of colors using the `lighter` and `darker` properties:

```toml
[colors.core]
border = { name = "colors.accents.blue", darker = 300 }

[colors.input]
# Reference the darkened border and make it slightly lighter
border_focus = { name = "colors.core.border", lighter = 100 }
```

There is no specific unit associated with lightness modification. The higher the number, the more pronounced the effect. Values should always be equal to or greater than zero.

### Combining Modifications

You can combine opacity and lightness modifications:

```toml
[colors.core]
subtle_accent = {
  name = "colors.accents.blue",
  darker = 150,
  opacity = 0.6
}
```

This creates a darker, semi-transparent version of the blue accent color.

## Color Reference Chains

Colors can reference other colors that themselves use complex modifications:

```toml
[colors.core]
accent = "#89B4FA"
border = { name = "colors.core.accent", darker = 200 }

[colors.input]
# This references the already-darkened border and makes it lighter
border_focus = { name = "colors.core.border", lighter = 50 }
```

Color reference chains enable complex color relationships.

## Troubleshooting

### Circular References

Avoid creating circular color references, as they will cause the theme to fail loading:

```toml
[colors.core]
background = "colors.core.foreground"
foreground = "colors.core.background"
```

### Fallback Behavior

If a color value is invalid or cannot be resolved, Vicinae will:

1. Check the parent theme for that color
2. Continue up the inheritance chain
3. Eventually fall back to the base theme (`vicinae-dark` or `vicinae-light`)

Themes will still load with some invalid values due to this fallback mechanism.

## Next Steps

* Explore [CLI tools](https://docs.vicinae.com/theming/cli-tools) for validating themes and debugging issues
* Review [theme structure](https://docs.vicinae.com/theming/theme-structure) for available color tables

---

# CLI Tools

The `vicinae` binary provides command-line tools for managing, validating, and debugging theme files.

## Available Commands

Run the following to see all theme-related commands:

```bash
vicinae theme --help
```

This will display the available subcommands and their options.

## Generate Theme Template

Create a complete theme template with all available color keys and documentation:

```bash
vicinae theme template > ~/.local/share/vicinae/themes/my-new-theme.toml
```

This command outputs a template to stdout, which you can redirect to a file. The template includes:

* All available metadata fields
* Every color table and key
* Inline comments explaining each option
* Example values

## Set Active Theme

Change the currently active theme from the command line:

```bash
vicinae theme set <theme_id>
```

The `theme_id` is the theme filename without the `.toml` extension. For example, if your theme file is named `catppuccin-mocha.toml`, use:

```bash
vicinae theme set catppuccin-mocha
```

## Typical Search Paths

The paths usually follow the XDG Base Directory specification:

1. `$HOME/.local/share/vicinae/themes` (user themes)
2. `/usr/local/share/vicinae/themes` (system-wide themes)
3. `/usr/share/vicinae/themes` (distribution themes)

It's recommended to place custom themes in `$HOME/.local/share/vicinae/themes` to avoid conflicts with system updates.

### Theme Shadowing

If two themes have the same filename in different search paths, only the first one will be loaded. This allows you to override system themes with custom versions:

```
~/.local/share/vicinae/themes/rose-pine.toml  ← This one loads
/usr/share/vicinae/themes/rose-pine.toml      ← This one is shadowed
```

## Theme Directory Structure

Theme directories must be flat - subdirectories are not searched. All theme files should be placed directly in the theme directory:

```
Correct:
~/.local/share/vicinae/themes/
├── my-theme.toml
├── another-theme.toml
└── catppuccin-mocha.toml

Incorrect (subdirectories won't be found):
~/.local/share/vicinae/themes/
└── custom/
    └── my-theme.toml
```

However, theme assets (like icons) can be in subdirectories and referenced relatively:

```toml
[meta]
icon = "icons/my-theme-icon.png"
```

This will look for `icons/my-theme-icon.png` relative to the theme file's location.

Theme directories are automatically watched. Changes to theme files are applied immediately without restarting Vicinae.

## Next Steps

* Review [theme structure](https://docs.vicinae.com/theming/theme-structure) for available color options
* Explore [advanced features](https://docs.vicinae.com/theming/advanced-features) for color manipulation
* Check out the [getting started guide](https://docs.vicinae.com/theming/getting-started) for quick setup

---

# Matugen Integration

Vicinae can easily integrate with [matugen](https://github.com/InioX/matugen) or other color palette generation tools to dynamically generate themes from wallpapers. This guide shows you how to set up matugen to automatically create and apply Vicinae themes based on your wallpaper colors.

## Prerequisites

Before you begin, make sure you have:

* [matugen](https://github.com/InioX/matugen) installed on your system
* A wallpaper manager (this guide uses `swww`, but you can adjust for others)

## Configuration

### Step 1: Configure matugen

Add the following configuration to your matugen config file (typically `~/.config/matugen/config.toml`):

```toml
# Adjust this if you set your wallpaper using another software
[config.wallpaper]
command = "swww"
arguments = ["img", "--transition-type", "center"]
set = true

[templates.vicinae]
input_path = './templates/vicinae.toml'
output_path = '~/.local/share/vicinae/themes/matugen.toml'
post_hook = 'vicinae theme set matugen'
```

The `post_hook` automatically applies the generated theme after matugen creates it.

### Step 2: Set up the Vicinae template

For the configuration to work, you need a Vicinae theme template that matugen can use to generate colors.

Download the official template:

```bash
mkdir -p ~/.config/matugen/templates
curl https://raw.githubusercontent.com/vicinaehq/vicinae/refs/heads/main/extra/matugen.toml > ~/.config/matugen/templates/vicinae.toml
```

You can also [view the template](https://raw.githubusercontent.com/vicinaehq/vicinae/refs/heads/main/extra/matugen.toml) to customize it for your needs.

## Usage

Once configured, generate a theme from any image:

```bash
matugen image /path/to/wallpaper.png
```

Matugen will:

1. Extract a color palette from the wallpaper
2. Generate a Vicinae theme using the template
3. Save it to `~/.local/share/vicinae/themes/matugen.toml`
4. Automatically apply the theme via the `post_hook`

Your Vicinae interface will update with colors that complement your wallpaper.

## Customization

You can modify the template at `~/.config/matugen/templates/vicinae.toml` to:

* Adjust which Material You colors map to which Vicinae theme properties
* Fine-tune color brightness or saturation
* Add custom color overrides

See the [theme structure documentation](https://docs.vicinae.com/theming/theme-structure) for available theme properties.

---

## Script Commands

Script commands are one of the easiest ways to extend Vicinae. They allow you to index regular scripts written in any programming language and execute them directly from the Vicinae root search.

Script commands are meant to make executing one-shot tasks easier and provide nice feedback. If you want to build complex extensions that render lists, grids, forms and integrate more deeply with Vicinae, you should look into making your own [extension](https://docs.vicinae.com/extensions/introduction).

Vicinae script commands are very similar to [Raycast script commands](https://github.com/raycast/script-commands), and are mostly compatible with them. Learn more about the [main differences](https://docs.vicinae.com/scripts/raycast-compatibility).

![](https://docs.vicinae.com/scripts/full-output-demo.gif)

# Getting started with script commands

Script commands are just scripts with a few additional directives on top, used to instruct Vicinae how to index and execute them.

## Where to put scripts

By default, scripts are sourced from system directories. A common directory to put scripts in is `~/.local/share/vicinae/scripts`.

Script directories can contain as many scripts as desired, and support subdirectories (max depth is limited to 5).

It is possible to add additional directories from which to source scripts in the settings.

## Example script

The only requirement for a script file is to be a plain text file with three directives on top. Here is a typical Python script:

```python
#!/usr/bin/env python3
# @vicinae.schemaVersion 1
# @vicinae.title My Script
# @vicinae.mode fullOutput

print("Hello world!")
```

## Understanding directives

The `@vicinae.schemaVersion` directive should always be set to 1 and may be used to introduce changes to the specification in the future.

The `@vicinae.title` directive tells Vicinae what name the script goes by, so that you can search it using this name.

The `@vicinae.mode` directive dictates how the output of the script should be presented. `fullOutput` will push a new view and print the output there.

These three directives are required in order for Vicinae to index the script, but other directives are available to further customize the script. See the [directives page](https://docs.vicinae.com/scripts/directives) for an exhaustive list.

Script files should be given executable permission. The shebang line on top `#!/usr/bin/env python3` indicates to the executable loader what interpreter should be used to execute the script.

Note that it is possible to specify a fully custom command line by using the `@vicinae.exec` directive, removing the need to make the script executable or use a shebang.

You can generate a script template similar to this one with the `vicinae script template --title "My Script" --lang=python` command.

## Reloading scripts

Script directories are scanned at startup and every once in a while, but can also be reloaded manually using the Vicinae "Reload Script Directories" command, directly available from the root search.

Only top-level script directories are watched for changes, not subdirectories.

---

Directives are special comments that configure how Vicinae indexes and executes your scripts. They appear at the top of script files and control everything from the script's display name to its output mode.

# Directives

Every directive should be expressed as an inline comment, on a single line.

| Directive | Description | Required |
|-----------|-------------|----------|
| `@vicinae.schemaVersion` | Schema version (currently always `1`) | Yes |
| `@vicinae.title` | Display name for the script in search | Yes |
| `@vicinae.mode` | Output mode (e.g., `fullOutput`, `silent`, `compact`).  See all [available modes](https://docs.vicinae.com/scripts/modes). | Yes |
| `@vicinae.icon` | Icon to show in the root search. Can be a file path, an emoji or an HTTPS url. Relative file paths are relative to the directory in which the script is located. | No |
| `@vicinae.argument{1...3}` | Arguments to provide as input to the script. Format is documented on the [arguments page](https://docs.vicinae.com/scripts/arguments) | No |
| `@vicinae.exec` | Custom command line to execute the script. Expressed as a JSON e.g `["/usr/bin/env", "python3", "--my-fancy-flag"]`. Removes the need for the script to have executable permission. | No |
| `@vicinae.keywords` | Additional keywords to index the script against. Expressed as a JSON e.g `["keyword1", "keyword2"]` | No |
| `@vicinae.description` | More info about what the script does, used for documentation | No |
| `@vicinae.author` | Author of the script. Used for documentation. | No |
| `@vicinae.authorURL` | Link to the author's GitHub page or website. Used for documentation. | No |

---

Arguments allow your scripts to receive user input at runtime. Scripts can accept up to 3 arguments.

![](https://docs.vicinae.com/scripts/arguments-demo.gif)

# Arguments

Arguments are specified using the `@vicinae.argument1`, `@vicinae.argument2`, and `@vicinae.argument3` directives. Each argument is defined as a JSON object with various configuration options.

Like any other directive, the JSON describing the argument needs to be on one single line.

## Example

Here's a script that accepts two text arguments:

```python
#!/usr/bin/env python3
# @vicinae.schemaVersion 1
# @vicinae.title My Python Script
# @vicinae.icon 🐍
# @vicinae.mode fullOutput
# @vicinae.argument1 { "type": "text", "placeholder": "from" }
# @vicinae.argument2 { "type": "text", "placeholder": "to", "optional": true }

import sys

source = sys.argv[1]
destination = sys.argv[2] if len(sys.argv) > 2 else None

print(source + " to " + destination)
```

## Argument Configuration

| Field | Description | Required |
|-------|-------------|----------|
| `type` | The argument type. Supported values: `"text"`, `"password"` (redacted text). | Yes |
| `placeholder` | Placeholder text for the input field. | Yes |
| `optional` | Set to `true` if you want to mark the argument as optional. The argument is considered required by default - vicinae will not allow executing the script if the argument is empty. | No |
| `percentEncoded` | URL encodes the text provided as an argument if set to true. | No |

---

Output modes control how script results are displayed in Vicinae. Choose the mode that best fits your script's purpose and output type.

# Output Modes

## Full output

The output of the script is displayed in a new view. Text can be selected and copied from there.

This mode supports basic ANSI color codes. This means you can use basic colors in your output and have them render properly. This is, for now, exclusive to this output mode.

![](https://docs.vicinae.com/scripts/full-output-demo.gif)

## Silent

The first output line of the script is shown in a little HUD after the window is closed.

Only available if Vicinae is using layer shell to position itself on the desktop

![](https://docs.vicinae.com/scripts/silent-demo.gif)

## Compact

The first output line of the script is shown in a toast notification.

![](https://docs.vicinae.com/scripts/compact-demo.gif)

## Inline

The first output line of the script is used as the command subtitle, and is refreshed on every execution.

![](https://docs.vicinae.com/scripts/inline-demo.gif)

## Terminal

The script is executed in a new terminal window. If the [default terminal](https://docs.vicinae.com/default-terminal) supports it, `--hold` or an equivalent flag is passed to keep the terminal window open even when the script is done executing.

![](https://docs.vicinae.com/scripts/terminal-demo.gif)

---

Vicinae script commands are mostly compatible with [Raycast script commands](https://github.com/raycast/script-commands). In most cases, you should be able to take any Raycast script command and use it with vicinae, provided that the script logic itself remains valid in your environment.

This means you can use `@raycast` instead of `@vicinae` for all directives that are supported by both systems. For directives that have been added by vicinae, only `@vicinae` is supported to avoid confusion.

Vicinae adds support for new directives such as `@vicinae.keywords` and `@vicinae.exec` and new output modes such as `terminal`.

Vicinae doesn't support arguments of type `dropdown` at this time, but this will likely change in the future.

---

## Getting Started

# Introduction

Vicinae extensions are written in TypeScript using React components. There is no browser involved: your code produces a serialized UI tree that the C++ core renders natively.

![](https://docs.vicinae.com/extensions/code.webp)

## How it works

You write declarative React components using the `@vicinae/api` package. When state changes, components rerender and Vicinae handles the rest. All standard Node.js APIs are available.

```tsx
import { ActionPanel, Action, List } from "@vicinae/api";
import { fruits } from "./data";

export default function FruitList() {
  return (
    <List isShowingDetail searchBarPlaceholder="Search fruits...">
      {fruits.map((fruit) => (
        <List.Item
          key={fruit.emoji}
          title={fruit.name}
          icon={fruit.emoji}
          detail={<List.Item.Detail markdown={fruit.description} />}
          actions={
            <ActionPanel>
              <Action.CopyToClipboard title="Copy emoji" content={fruit.emoji} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}
```

![](https://docs.vicinae.com/extensions/intro-example.webp)

Search, markdown rendering, and keyboard navigation all work automatically.

## Raycast compatibility

Our API closely follows the [Raycast](https://developers.raycast.com/) API, and our long-term goal is compatibility with most existing Raycast extensions. We also offer exclusive APIs where it makes sense.

Since Vicinae is open source and community-driven, we prioritize API features that users want most.

---

# Create your first extension

This page explains how to create your first extension.

## Requirements

In order to develop extensions, you will need:

* A working installation of Node.js (>=20 recommended). If you are on Linux, your package manager may have handled that for you already.
* An npm-compatible package manager such as `npm` or `pnpm`. We always use `npm` in our examples.
* Basic knowledge of [TypeScript](https://www.typescriptlang.org/) and [React](https://react.dev/). No need to be an expert to build simple extensions.

## Create Your Extension

The most straightforward way to create an extension is to use the [Create Extension](vicinae:///extensions/vicinae/extensionseloper/create) command from within Vicinae:

![](https://docs.vicinae.com/extensions/create-extension.webp)

Fill in all the fields, then press `Shift + Enter` to create the extension:

![](https://docs.vicinae.com/extensions/create-extension-success.webp)

As instructed, move to your newly created extension directory and install the required dependencies:

```bash
npm install
```

Once that is done, start your extension in development mode (Vicinae needs to be running):

```bash
npm run dev
```

If all is going well, the command should output something like this:

![](https://docs.vicinae.com/extensions/extension-dev-logs.webp)

Your extension should now come up when searching for it in the root search:

![](https://docs.vicinae.com/extensions/first-extension-root.webp)

And then simply open it for the first time:

![](https://docs.vicinae.com/extensions/first-extension-running.webp)

Notice the `(Dev)` suffix in the navigation title. This means you are running the command as part of a development session.
In this mode, the development version of React is used and the command outputs its logs to the console where you started the session.
&#x20;In development mode, the extension is also updated every time you save a file.

## Where to go from here

* [Learn about the file structure](https://docs.vicinae.com/extensions/file-structure)
* [Learn about the manifest file](https://docs.vicinae.com/extensions/manifest)
* [Explore the API reference](https://docs.vicinae.com/extensions/api)

---

# Create a view command

In Vicinae, a view command is a command that pushes new UI views on the navigation stack.

## Declaring a view command

In order to declare a command as a view command, you need to set the `mode` of the command to `view` inside the manifest:

```json
{
  "name": "my-first-command",
  "title": "My First Command",
  "subtitle": "My first subtitle",
  "description": "My first command description",
  "mode": "view"
}
```

This command declaration expects the presence of a corresponding `src/my-first-command.tsx` entrypoint file.

Be careful about the file extension: you need to use `.tsx` for view commands as we are dealing with TSX.

## View command implementation

From the entrypoint, all you need to do is to export a React component as the default export:

```tsx {{ title: 'my-first-command.tsx' }}
import { Detail, ActionPanel, Action, showToast } from '@vicinae/api';

export default function MyFirstCommand() {
	return (
		<Detail
			markdown={md}
			actions={
				<ActionPanel>
					<Action 
						title="Say hello" 
						onAction={() => showToast({ title: 'Hello!' })} 
					/>
				</ActionPanel>
			}
		/>
	);
}
```

When your command is launched from the root search, Vicinae will automatically push a new view on the stack, which will get hydrated as your
extension is loaded.

## Root component types

A Vicinae view must use one of the supported root component types. Here are the main ones:

* `List` - a vertical list with an optional detail panel.
* `Grid` - a grid layout for visual content.
* `Detail` - a markdown view with an optional metadata sidebar.
* `Form` - a form with various input types.

For a full list of available root components, please refer to the [API Reference](https://docs.vicinae.com/extensions/api).

Returning an element that is not of one of the supported root types will throw an error.

Don't even try to return HTML.

## Pushing more views

A view command is not limited to a single view. It can push and pop views on the navigation stack.

To do that, all you need is the `useNavigation` hook:

```tsx
import { 
	Detail, ActionPanel, Action, 
	showToast, List, Icon, 
	useNavigation 
} from '@vicinae/api';

// View to push on top of the main view
const ListView = () => {
	const { push, pop } = useNavigation();

	return (
		<List>
			<List.Item 
				title={"Push myself"} 
				icon={Icon.Sun} 
				actions={
					<ActionPanel>
						<Action 
							title="push myself!" 
							icon={Icon.Window} 
							onAction={() => push(<ListView />)} 
						/>
					</ActionPanel>
				}
			/>
			<List.Item 
				title={"Pop myself"} 
				icon={Icon.Moon} 
				actions={
					<ActionPanel>
						<Action 
							title="pop myself!" 
							icon={Icon.Bolt} 
							onAction={pop} 
						/>
					</ActionPanel>
				}
			/>
		</List>
	)
}

// Main view
export default function MyFirstCommand() {
	const { push } = useNavigation();

	return (
		<Detail
			markdown={md}
			actions={
				<ActionPanel>
					{/** Note: <Action.PushView> should generally be used 
					  instead, but we show it for demonstration purposes */}
					<Action 
						title="Push a new view" 
						icon={Icon.AppWindow}
						onAction={() => push(<ListView />)} 
					/>
				</ActionPanel>
			}
		/>
	);
}
```

There is no hard limit on how many views a command can push on the stack.
However, pushing more than 5 views deep probably suggests that your command does too much!

---

# Create a no-view command

In Vicinae, a no-view command is a command that directly executes from within the root search, without pushing new UI.

## Declaring a no-view command

In order to declare a command as a no-view command, you need to set the `mode` of the command to `no-view` inside the manifest:

```json
{
  "name": "my-first-command",
  "title": "My First Command",
  "subtitle": "My first subtitle",
  "description": "My first command description",
  "mode": "no-view"
}
```

This command declaration expects the presence of a corresponding `src/my-first-command.ts` entrypoint file.

## No-View Lifecycle

When a no-view command is launched from the root search, the code inside the function starts executing immediately.
The command is unloaded when the function returns **or** if another command is launched (command execution is non-blocking).

No-view commands are not meant to execute long-running logic. There is currently no way for extensions to do this outside of using external daemons (not recommended).
This will likely be addressed in the future.

## No-view command implementation

From the entrypoint, all you need to do is to export an async function as the default export:

```ts {{ title: 'my-first-command.ts' }}
import { showToast } from '@vicinae/api';

export default async function MyFirstCommand() {
	await showToast({ title: 'Hello from no-view command!' });
}
```

Make sure to properly `await` asynchronous API calls. Otherwise, the command might be unloaded before the promises resolve.

Any attempt to use navigation features from no-view commands will be met with an error. You can, however, use other Vicinae APIs all the same.

---

# File Structure

This page describes the file structure of a Vicinae extension.

A valid Vicinae extension is a directory containing at least two things:

* a manifest file named `package.json`, which is a regular `package.json` file with Vicinae-specific additions.
* one or more command entrypoints under the `src` subdirectory, such as `src/command_name.tsx`. Each must map to a valid command name in the manifest.

This is what a typical extension directory looks like:

```bash
my-first-extension
    ├── assets
    │   └── extension_icon.webp
    ├── package.json
    ├── package-lock.json
    ├── README.md
    ├── src
    │   └── my-first-command.tsx
    └── tsconfig.json
```

We may add configuration files for JavaScript tooling in the future (eslint, prettier, etc.).

## Source directory

The source directory should contain all your source files (not only command entrypoints).

For each command defined in the extension manifest, you need to have a corresponding entrypoint directly under `src`.

For a command named `my-command`, you need a corresponding `src/my-command.tsx` or `src/my-command.ts` entrypoint.

You should use the `.ts` extension for no-view commands and the `.tsx` extension for view commands.
Using `.tsx` for no-view commands is still supported but not the other way around.

## Assets directory

The `assets` directory contains icons and other files that are packaged into the extension bundle. All assets can be referenced at runtime and used as images where Vicinae expects them. This is also where extension or command icons referenced in the manifest should be placed.

## Other files

* `node_modules`: dependencies required for the extension to run. Do not modify this directory manually.
* `package-lock.json`: locked versions of the dependencies. Do not edit directly.

---

# Manifest

The extension manifest extends the regular `package.json` format found in npm-managed JavaScript projects.

It contains information about dependencies, but also extension-specific fields such as what commands the extension exports, their preferences, arguments, etc.

Our manifest documentation is still incomplete. You can refer to the [Raycast documentation](https://developers.raycast.com/information/manifest) for an exhaustive list of supported keys, as we share the same manifest format.
None of what's discussed here is specific to Vicinae.

## Anatomy of a manifest

This is what the manifest from the [create extension page](https://docs.vicinae.com/extensions/create) looks like:

```json
{
  "name": "my-first-extension",
  "title": "My First Extension",
  "description": "This is my very first extension",
  "categories": [],
  "license": "MIT",
  "author": "aurelle",
  "contributors": [],
  "pastContributors": [],
  "icon": "extension_icon.webp",
  "commands": [
    {
      "name": "my-first-command",
      "title": "My First Command",
      "subtitle": "My first subtitle",
      "description": "My first command description",
      "mode": "view"
    }
  ],
  "preferences": [],
  "scripts": {
    "build": "vici build",
    "dev": "vici develop"
  },
  "dependencies": {
    "@vicinae/api": "^0.8.2"
  },
  "devDependencies": {
    "typescript": "^5.9.2"
  }
}
```

Some fields are particularly interesting to us:

* `name`: the identifier of the extension, which should be in a sluggified format.
* `title`: the display name of an extension, which will be shown to users.
* `author`: the author of the extension. Needs to be a single username. This is used for a variety of things inside Vicinae.
* `icon` is used to resolve the extension's icon at runtime. Vicinae looks for it relative to the extension's `assets` directory. The same applies to command icons, if specified.
* `commands` lists all the available commands for this extension. The `name` key for each command should map to a proper command entrypoint under `src`. In this case, `src/my-first-command.tsx` is expected. At least one command should be specified to make it a valid extension.

## Dealing with preferences

### Anatomy of a preference object

An extension and each of its commands can declare preferences that must be set before they can run.

This is useful for requiring the user to provide an access token, tweaking command behavior, and more.

A preference object looks like this:

```json
{
	"name": "access-token",
	"title": "Access Token",
	"description": "The access token required to access the service",
	"required": true,
	"type": "password"
}
```

* `name` is the identifier of the preference, which should remain in slugified form
* `title` is the display name of the preference, shown to users
* `required` indicates whether the preference must be set. If required and no default value is provided, Vicinae will ask the user to supply it before the command can start.
* `type` is the type of preference. Currently supported: `textfield`, `password`, `checkbox`, `dropdown`, `file`, and `directory`.

If a preference is of type `dropdown` an additional `data` field is expected:

```json
{
  "name": "artwork",
  "title": "Artwork Style",
  "description": "Choose the preferred artwork style for Pokémon.",
  "required": false,
  "type": "dropdown",
  "default": "official",
  "data": [
	{
	  "title": "Official Artwork",
	  "value": "official"
	},
	{
	  "title": "Pixel Art",
	  "value": "pixel"
	}
  ]
} 
```

### Add preferences

To specify extension preferences, fill in the top-level `preferences` array with preference objects.

You can do the same for each command inside `commands` to specify command-level preferences.

Extension preferences are shared across all commands of that same extension whereas command preferences are only considered for the command it's specified for.

---

# Arguments

Arguments are values the user provides inline when launching a command. They appear as input fields next to the command name in Vicinae. A command can have up to 3 arguments.

## Declaring arguments

Add an `arguments` array to a command in your `package.json`:

```json
{
  "commands": [
    {
      "name": "search-fruits",
      "title": "Search Fruits",
      "description": "Search for a fruit by name",
      "mode": "view",
      "arguments": [
        {
          "name": "query",
          "placeholder": "Fruit name",
          "type": "text",
          "required": true
        }
      ]
    }
  ]
}
```

## Reading arguments

Arguments are passed to your command via `LaunchProps`:

```tsx
import { LaunchProps, List } from "@vicinae/api";

export default function Command(props: LaunchProps<{ arguments: { query: string } }>) {
  const { query } = props.arguments;

  return (
    <List searchBarPlaceholder={`Results for "${query}"...`}>
      {/* filtered items */}
    </List>
  );
}
```

## Argument types

| Type | Description |
| --- | --- |
| `text` | Free-form text input |
| `password` | Masked text input |
| `dropdown` | A predefined list of values |

## Dropdown arguments

For `dropdown` type arguments, provide a `data` array with the available options:

```json
{
  "name": "category",
  "placeholder": "Category",
  "type": "dropdown",
  "required": false,
  "data": [
    { "title": "Berry", "value": "berry" },
    { "title": "Citrus", "value": "citrus" },
    { "title": "Tropical", "value": "tropical" }
  ]
}
```

---

# Preferences

Preferences are persistent settings that the user configures before running your extension. Vicinae shows them in the settings window and prompts the user for required values before the first run.

## Declaring preferences

Add a `preferences` array at the top level of your `package.json` for extension-wide preferences, or inside a specific command for command-level preferences:

```json
{
  "preferences": [
    {
      "name": "api-key",
      "title": "API Key",
      "description": "Your API key for the fruit service",
      "type": "password",
      "required": true
    },
    {
      "name": "show-details",
      "title": "Show Details",
      "description": "Show the detail panel by default",
      "type": "checkbox",
      "default": false,
      "required": false
    }
  ]
}
```

Extension preferences are shared across all commands. Command preferences only apply to the command they are declared on and can override extension preferences with the same `name`.

## Reading preferences

Use `getPreferenceValues` to access the current values at runtime:

```tsx
import { getPreferenceValues } from "@vicinae/api";

interface Preferences {
  "api-key": string;
  "show-details": boolean;
}

const prefs = getPreferenceValues<Preferences>();
```

## Preference types

| Type | Description |
| --- | --- |
| `textfield` | Free-form text input |
| `password` | Masked text input for secrets |
| `checkbox` | Boolean toggle |
| `dropdown` | A predefined list of values |
| `file` | File picker |
| `directory` | Directory picker |

## Dropdown preferences

For `dropdown` type preferences, provide a `data` array:

```json
{
  "name": "artwork",
  "title": "Artwork Style",
  "description": "Choose the preferred artwork style",
  "type": "dropdown",
  "default": "official",
  "required": false,
  "data": [
    { "title": "Official Artwork", "value": "official" },
    { "title": "Pixel Art", "value": "pixel" }
  ]
}
```

## Opening preferences programmatically

Navigate the user to the settings window directly from your extension:

```tsx
import { openExtensionPreferences, openCommandPreferences } from "@vicinae/api";

await openExtensionPreferences();
await openCommandPreferences();
```

---

# Raycast Compatibility

## Compatibility Goals

Raycast extensions are compatible with Vicinae, and that is one of the goals of this project. Some Raycast extensions use APIs that may not be available on all platforms, but most things have their counterpart in Vicinae.

Native Vicinae extensions are developed using the `@vicinae/api` package, which is **not** strictly compatible with `@raycast/api`. The tooling (development sessions, production builds) is also different between the two.

The general goal is to remain compatible with Raycast without restricting ourselves to their model.

This is why we also have our own [extension store](https://www.vicinae.com/extensions).

## Debug Raycast Extensions

Vicinae is compatible with most Raycast extensions, so you can run them in development mode as you would any Vicinae extension.

### Get Raycast Extensions (optional)

Extensions installed from the Raycast store cannot be debugged directly as they are already bundled for production.

If you want to debug a Raycast extension published to the official store, you need to download the source code.

Official Raycast extensions are maintained in a [single git repository](https://github.com/raycast/extensions), so start by cloning it:

```bash
git clone https://github.com/raycast/extensions
```

Then find the extension you are interested in by navigating to the `extensions/<extension_name>` directory.

Installing the store version of an extension and debugging it from source at the same time is not recommended. They are technically two different extensions, and this will result in duplicates in the UI which may make it hard to differentiate the store version from the development one.

### Install Vicinae SDK

To run a Raycast extension in development mode, install the Vicinae SDK as you would for any Vicinae extension.

From the extension source tree, run:

```bash
npm install
npm install --save-dev @vicinae/api
```

You cannot simply run `npm run dev` since for a Raycast extension, this would invoke the `ray` binary which only works with Raycast.

Instead, explicitly invoke the `vici` CLI exported from the `@vicinae/api` package:

```bash
npx vici develop
```

This should work seamlessly as it does for any other extension.

When debugging a Raycast extension, make sure you use exports from the `@raycast/api` package and not from the `@vicinae/api` one. Mixing them will work but may yield unexpected results.

---

## User Interface

# List

A searchable, scrollable list of items with optional detail panels, accessories, and filters.

![List](https://docs.vicinae.com/extensions/api/list/accessories.png)

## Basic List

```tsx
import { Action, ActionPanel, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard title="Copy" content="🍎" />
          </ActionPanel>
        }
      />
      <List.Item title="Banana" icon="🍌" />
      <List.Item title="Cherry" icon="🍒" />
    </List>
  );
}
```

## Detail Panel

Set `isShowingDetail` to show a side panel with markdown and metadata.

```tsx
import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Apple"
        icon="🍎"
        detail={
          <List.Item.Detail
            markdown="# Apple\n\nA crisp, sweet fruit."
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Color" text="Red" />
                <List.Item.Detail.Metadata.TagList title="Season">
                  <List.Item.Detail.Metadata.TagList.Item text="Autumn" color={Color.Orange} />
                </List.Item.Detail.Metadata.TagList>
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
      {/* ... */}
    </List>
  );
}
```

## Accessories

Right-side metadata supporting text, colored tags, and icons.

```tsx
import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        accessories={[
          { text: "95 kcal" },
          { tag: { value: "fruit", color: Color.Red } },
        ]}
      />
      {/* ... */}
    </List>
  );
}
```

## Empty View

Placeholder when the list has no items.

```tsx
import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.EmptyView
        title="No Fruits Found"
        description="Try a different search."
        icon={{ source: "🍎", tintColor: Color.SecondaryText }}
      />
    </List>
  );
}
```

## Dropdown Filter

Filter items via a dropdown in the search bar.

```tsx
import { useState } from "react";
import { List } from "@vicinae/api";

export default function Command() {
  const [type, setType] = useState("all");

  return (
    <List
      searchBarAccessory={
        <List.Dropdown tooltip="Type" value={type} onChange={setType}>
          <List.Dropdown.Item title="All" value="all" />
          <List.Dropdown.Item title="Berries" value="berry" />
          <List.Dropdown.Item title="Citrus" value="citrus" />
        </List.Dropdown>
      }
    >
      {/* filtered items */}
    </List>
  );
}
```

## Controlled Search

Handle search yourself by controlling `searchText`. This automatically disables built-in filtering.

```tsx
import { useState } from "react";
import { List } from "@vicinae/api";

export default function Command() {
  const [query, setQuery] = useState("");

  return (
    <List searchText={query} onSearchTextChange={setQuery}>
      {/* manually filtered items */}
    </List>
  );
}
```

---

# Grid

A searchable grid layout for visual content like images, icons, or colors.

![](https://docs.vicinae.com/extensions/api/grid/grid.png)

## Basic Grid

```tsx
import { Grid } from "@vicinae/api";

export default function Command() {
  return (
    <Grid columns={4}>
      <Grid.Item content="🍎" title="Apple" />
      <Grid.Item content="🍌" title="Banana" />
      <Grid.Item content="🍒" title="Cherry" />
      <Grid.Item content="🍊" title="Orange" />
      <Grid.Item content="🍇" title="Grape" />
      <Grid.Item content="🍓" title="Strawberry" />
    </Grid>
  );
}
```

## Sections

```tsx
import { Grid } from "@vicinae/api";

export default function Command() {
  return (
    <Grid columns={5}>
      <Grid.Section title="Berries">
        <Grid.Item content="🍓" title="Strawberry" />
        <Grid.Item content="🫐" title="Blueberry" />
        <Grid.Item content="🍇" title="Grape" />
      </Grid.Section>
      <Grid.Section title="Citrus">
        <Grid.Item content="🍊" title="Orange" />
        <Grid.Item content="🍋" title="Lemon" />
      </Grid.Section>
    </Grid>
  );
}
```

## Color Swatches

Grid items can display solid colors instead of images.

```tsx
import { Color, Grid } from "@vicinae/api";

export default function Command() {
  return (
    <Grid columns={6} aspectRatio="1">
      <Grid.Item content={{ color: Color.Red }} title="Red" />
      <Grid.Item content={{ color: Color.Orange }} title="Orange" />
      <Grid.Item content={{ color: Color.Yellow }} title="Yellow" />
      <Grid.Item content={{ color: Color.Green }} title="Green" />
      <Grid.Item content={{ color: Color.Blue }} title="Blue" />
      <Grid.Item content={{ color: Color.Purple }} title="Purple" />
    </Grid>
  );
}
```

## Aspect Ratio and Fit

Control the shape of grid cells and how content fills them.

```tsx
import { Grid } from "@vicinae/api";

export default function Command() {
  return (
    <Grid columns={3} aspectRatio="3/2" fit={Grid.Fit.Fill}>
      <Grid.Item content="https://example.com/apple.jpg" title="Apple" />
      <Grid.Item content="https://example.com/banana.jpg" title="Banana" />
      {/* ... */}
    </Grid>
  );
}
```

## Inset

Control spacing around grid items with `inset`.

```tsx
import { Grid } from "@vicinae/api";

export default function Command() {
  return (
    <Grid columns={4} inset={Grid.Inset.Large}>
      <Grid.Item content="🍎" title="Apple" />
      <Grid.Item content="🍌" title="Banana" />
      {/* ... */}
    </Grid>
  );
}
```

---

# Detail

A full-page markdown view with an optional metadata sidebar.

![](https://docs.vicinae.com/extensions/api/detail/detail.png)

## Basic Detail

```tsx
import { Action, ActionPanel, Detail } from "@vicinae/api";

export default function Command() {
  return (
    <Detail
      markdown="# Apple 🍎\n\nA crisp, sweet fruit popular in pies and cider.\n\n- Low calorie\n- High in fiber\n- Rich in antioxidants"
      actions={
        <ActionPanel>
          <Action.CopyToClipboard title="Copy Emoji" content="🍎" />
        </ActionPanel>
      }
    />
  );
}
```

## Metadata

Add a structured sidebar alongside the markdown content.

```tsx
import { Color, Detail } from "@vicinae/api";

export default function Command() {
  return (
    <Detail
      markdown="# Apple 🍎\n\nA crisp, sweet fruit."
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.Label title="Calories" text="95 kcal" />
          <Detail.Metadata.Label title="Type" text="Pome" />
          <Detail.Metadata.Separator />
          <Detail.Metadata.TagList title="Season">
            <Detail.Metadata.TagList.Item text="Autumn" color={Color.Orange} />
            <Detail.Metadata.TagList.Item text="Winter" color={Color.Blue} />
          </Detail.Metadata.TagList>
          <Detail.Metadata.Link
            title="Wikipedia"
            target="https://en.wikipedia.org/wiki/Apple"
            text="Learn more"
          />
        </Detail.Metadata>
      }
    />
  );
}
```

---

# Form

Collect user input through text fields, checkboxes, dropdowns, date pickers, and file pickers.

![](https://docs.vicinae.com/extensions/api/form/form.png)

## Basic Form

```tsx
import { Action, ActionPanel, Form, showToast } from "@vicinae/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit"
            onSubmit={(values) => showToast({ title: `Added ${values.name}` })}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" title="Name" placeholder="Apple" />
      <Form.TextArea id="description" title="Description" placeholder="A crisp, sweet fruit..." />
      <Form.Checkbox id="organic" label="Organic" />
    </Form>
  );
}
```

## Dropdown

```tsx
import { Form } from "@vicinae/api";

export default function Command() {
  return (
    <Form>
      <Form.Dropdown id="type" title="Type">
        <Form.Dropdown.Item title="Berry" value="berry" icon="🍓" />
        <Form.Dropdown.Item title="Citrus" value="citrus" icon="🍊" />
        <Form.Dropdown.Item title="Tropical" value="tropical" icon="🥭" />
      </Form.Dropdown>
    </Form>
  );
}
```

## DatePicker

```tsx
import { Form } from "@vicinae/api";

export default function Command() {
  return (
    <Form>
      <Form.DatePicker id="harvestDate" title="Harvest Date" type={Form.DatePicker.Type.Date} />
      <Form.DatePicker id="expiresAt" title="Expires At" type={Form.DatePicker.Type.DateTime} />
    </Form>
  );
}
```

## FilePicker

```tsx
import { Form } from "@vicinae/api";

export default function Command() {
  return (
    <Form>
      <Form.FilePicker id="photo" title="Photo" />
      <Form.FilePicker id="gallery" title="Gallery" allowMultipleSelection />
      <Form.FilePicker id="folder" title="Folder" canChooseDirectories canChooseFiles={false} />
    </Form>
  );
}
```

## Validation

Use `error` to show validation messages on individual fields.

```tsx
import { useState } from "react";
import { Action, ActionPanel, Form } from "@vicinae/api";

export default function Command() {
  const [nameError, setNameError] = useState<string | undefined>();

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField
        id="name"
        title="Name"
        error={nameError}
        onChange={(value) => setNameError(value.length === 0 ? "Required" : undefined)}
        onBlur={(event) => {
          if (!event.target.value) setNameError("Required");
        }}
      />
    </Form>
  );
}
```

## Separator and Description

Use `Form.Separator` to visually group fields and `Form.Description` for help text.

```tsx
import { Form } from "@vicinae/api";

export default function Command() {
  return (
    <Form>
      <Form.TextField id="name" title="Name" />
      <Form.Separator />
      <Form.Description title="Note" text="Nutritional values are approximate." />
      <Form.TextField id="calories" title="Calories" placeholder="95" />
    </Form>
  );
}
```

---

# ActionPanel

A container for actions the user can perform on the current item. Attach it to `List.Item`, `Grid.Item`, `Detail`, or `Form` via the `actions` prop.

## Basic ActionPanel

```tsx
import { Action, ActionPanel, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard title="Copy Emoji" content="🍎" />
            <Action.OpenInBrowser title="Wikipedia" url="https://en.wikipedia.org/wiki/Apple" />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

## Sections

Group related actions under titled sections. The first action in the first section is the default.

```tsx
import { Action, ActionPanel, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <ActionPanel.Section title="Copy">
              <Action.CopyToClipboard title="Copy Emoji" content="🍎" />
              <Action.CopyToClipboard title="Copy Name" content="Apple" />
            </ActionPanel.Section>
            <ActionPanel.Section title="Other">
              <Action.OpenInBrowser title="Wikipedia" url="https://en.wikipedia.org/wiki/Apple" />
            </ActionPanel.Section>
          </ActionPanel>
        }
      />
    </List>
  );
}
```

## Submenu

Nest a group of actions under a submenu for less common operations.

```tsx
import { Action, ActionPanel, Icon, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard title="Copy Emoji" content="🍎" />
            <ActionPanel.Submenu title="Share" icon={Icon.Link}>
              <Action.CopyToClipboard title="Copy as Markdown" content="[Apple](🍎)" />
              <Action.Paste title="Paste Emoji" content="🍎" />
            </ActionPanel.Submenu>
          </ActionPanel>
        }
      />
    </List>
  );
}
```

---

# Actions

Individual operations that live inside an `ActionPanel`. Vicinae ships several built-in actions for common tasks.

## Action

The base component for custom actions.

```tsx
<Action title="Say Hello" icon={Icon.SpeechBubble} onAction={() => console.log("Hello!")} />
```

All the other actions listed below except `<Action.Submit />` are wrappers around `<Action />` and exposed Vicinae APIs, provided for convenience and saner defaults.

## Action.CopyToClipboard

Copy text to the clipboard. Shows a confirmation toast automatically.

```tsx
<Action.CopyToClipboard title="Copy Emoji" content="🍎" />
```

Pass `concealed` to prevent the content from being indexed by the clipboard manager.

## Action.Paste

Paste content into the frontmost application.

```tsx
<Action.Paste title="Paste Emoji" content="🍎" />
```

## Action.OpenInBrowser

Open a URL in the default browser.

```tsx
<Action.OpenInBrowser title="Wikipedia" url="https://en.wikipedia.org/wiki/Apple" />
```

## Action.Open

Open a file or URL with the default or a specific application.

```tsx
<Action.Open title="Open File" target="/path/to/file.txt" />
```

## Action.OpenWith

Open a file with a specific application chosen by the user.

```tsx
<Action.OpenWith title="Open With..." path="/path/to/image.png" />
```

## Action.Push

Push a new view onto the navigation stack.

```tsx
<Action.Push title="Show Details" target={<Detail markdown="# Apple 🍎" />} />
```

## Action.SubmitForm

Submit a form. Typically the primary action inside a `Form`.

```tsx
<Action.SubmitForm title="Save" onSubmit={(values) => console.log(values)} />
```

## Action.Trash

Move files to the trash.

```tsx
<Action.Trash title="Delete" paths={["/path/to/file.txt"]} />
```

## Action.ShowInFinder

Reveal a file in the system file browser.

```tsx
<Action.ShowInFinder title="Reveal" path="/path/to/file.txt" />
```

## Action.RunInTerminal

Run a command in a new terminal window.

```tsx
<Action.RunInTerminal title="Run Tests" args={["npm", "test"]} />
```

## Keyboard Shortcuts

Bind a shortcut to any action. Use named shortcuts from `Keyboard.Shortcut.Common` when possible.

```tsx
import { Action, Keyboard } from "@vicinae/api";

<Action.CopyToClipboard
  title="Copy"
  content="🍎"
  shortcut={Keyboard.Shortcut.Common.Copy}
/>
```

## Destructive Style

Mark an action as destructive to visually warn the user.

```tsx
<Action title="Delete" style="destructive" onAction={() => {}} />
```

---

# Images

Anywhere the API accepts an image (`icon`, `content`, etc.), you can pass one of these types:

```tsx
import { Color, Icon, Image, List } from "@vicinae/api";

// Built-in icon
<List.Item title="Settings" icon={Icon.Cog} />

// Emoji
<List.Item title="Apple" icon="🍎" />

// Asset file (from the extension's assets directory)
<List.Item title="Logo" icon="logo.png" />

// Remote URL
<List.Item title="Avatar" icon="https://example.com/avatar.png" />

// File icon (system icon for a file type)
<List.Item title="Document" icon={{ fileIcon: "/path/to/file.pdf" }} />

// Tinted icon
<List.Item title="Error" icon={{ source: Icon.XMarkCircle, tintColor: Color.Red }} />

// Themed (light/dark variants)
<List.Item title="Logo" icon={{ light: "logo-light.png", dark: "logo-dark.png" }} />

// Circle mask
<List.Item title="User" icon={{ source: "avatar.png", mask: Image.Mask.Circle }} />

// With fallback (used if source fails to load)
<List.Item
  title="Profile"
  icon={{ source: "https://example.com/avatar.png", fallback: Icon.Person }}
/>
```

## Icons

The `Icon` enum provides hundreds of built-in icons covering UI elements, technology logos, and general-purpose symbols. Refer to the TypeScript types for the complete list.

```tsx
import { Icon } from "@vicinae/api";

Icon.Star
Icon.MagnifyingGlass
Icon.Download
Icon.Cog
```

## Image Object

For tinting, masking, fallbacks, or theming, pass an object instead of a plain source.

| Property | Type | Description |
| --- | --- | --- |
| `source` | `Icon \| string \| ThemedSource` | Icon enum value, asset path, URL, or `{ light, dark }` object |
| `fallback` | `Icon \| string \| ThemedSource` | Image to use if `source` fails to load |
| `tintColor` | `Color \| string` | Color applied over the image |
| `mask` | `Image.Mask` | Shape mask applied to the image |

## Themed Images

Provide different assets for light and dark themes by passing an object with `light` and `dark` keys as the source.

```tsx
const icon = { light: "icon-light.png", dark: "icon-dark.png" };
```

## Image.Mask

| Value | Description |
| --- | --- |
| `Image.Mask.Circle` | Circular crop |
| `Image.Mask.RoundedRectangle` | Rounded rectangle crop |

---

# Colors

Semantic colors for tags, icons, tints, and backgrounds across the extension UI.

## Color Enum

Use the built-in `Color` enum for consistent colors that adapt to the theme.

```tsx
import { Color, List } from "@vicinae/api";

<List.Item
  title="Apple"
  accessories={[{ tag: { value: "fruit", color: Color.Red } }]}
/>
```

| Value | Usage |
| --- | --- |
| `Color.Red` | Errors, destructive |
| `Color.Orange` | Warnings |
| `Color.Yellow` | Caution |
| `Color.Green` | Success |
| `Color.Blue` | Info, links |
| `Color.Purple` | Accents |
| `Color.Magenta` | Accents |
| `Color.PrimaryText` | Primary text color |
| `Color.SecondaryText` | Muted text color |

## Raw Colors

Pass any CSS color string where a `ColorLike` is expected.

```tsx
import { List } from "@vicinae/api";

<List.Item
  title="Custom"
  accessories={[{ tag: { value: "custom", color: "#ff6b6b" } }]}
/>
```

## Dynamic Colors

Provide different colors for light and dark themes.

```tsx
const dynamicColor = { light: "#000000", dark: "#ffffff" };
```

---

## Navigation

# useNavigation

Push and pop views on the navigation stack from within a command.

In most cases, prefer `<Action.Push />` over calling `push` directly.

## Push a View

```tsx
import { Action, ActionPanel, Detail, List, useNavigation } from "@vicinae/api";

function FruitDetail({ name, emoji }: { name: string; emoji: string }) {
  return <Detail markdown={`# ${name} ${emoji}`} />;
}

export default function Command() {
  const { push } = useNavigation();

  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <Action title="View" onAction={() => push(<FruitDetail name="Apple" emoji="🍎" />)} />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

## Pop Back

```tsx
import { Action, ActionPanel, Detail, useNavigation } from "@vicinae/api";

function FruitDetail() {
  const { pop } = useNavigation();

  return (
    <Detail
      markdown="# Apple 🍎"
      actions={
        <ActionPanel>
          <Action title="Go Back" onAction={pop} />
        </ActionPanel>
      }
    />
  );
}
```

---

## Feedback

# Toast

Brief feedback notifications at the bottom of the Vicinae window.

![](https://docs.vicinae.com/extensions/api/toast/toast.png)

## showToast

```tsx
import { showToast, Toast } from "@vicinae/api";

await showToast({ title: "Fruit added", style: Toast.Style.Success });
```

Non-animated toasts will automatically be dismissed after some time. This is not configurable at the extension level.

It is undefined behavior to show multiple toasts at once: no specific order is guaranteed.

## Styles

| Style | Description |
| --- | --- |
| `Toast.Style.Success` | Something succeeded |
| `Toast.Style.Failure` | Something failed |
| `Toast.Style.Animated` | Spinning indicator for ongoing operations |

## Animated Toast

Show a loading toast and update it when the operation completes.

```tsx
import { showToast, Toast } from "@vicinae/api";

const toast = await showToast({ title: "Uploading...", style: Toast.Style.Animated });

// ... do work ...

// assigning these properties immediately updates the toast
toast.style = Toast.Style.Success;
toast.title = "Upload complete";
```

## Error Handling

```tsx
import { showToast, Toast } from "@vicinae/api";

try {
  await fetchFruits();
  await showToast({ title: "Loaded fruits" });
} catch (error) {
  await showToast({ title: "Failed to load", message: String(error), style: Toast.Style.Failure });
}
```

---

# Alert

A confirmation dialog for destructive or important actions. The user must explicitly confirm or cancel.

![](https://docs.vicinae.com/extensions/api/alert/alert.png)

## confirmAlert

```tsx
import { confirmAlert, Alert } from "@vicinae/api";

const confirmed = await confirmAlert({
  title: "Delete Apple?",
  message: "This cannot be undone.",
  primaryAction: {
    title: "Delete",
    style: Alert.ActionStyle.Destructive,
  },
});

if (confirmed) {
  // delete the fruit
}
```

## Action Styles

| Style | Description |
| --- | --- |
| `Alert.ActionStyle.Default` | Standard confirm button |
| `Alert.ActionStyle.Destructive` | Red, used for irreversible actions |
| `Alert.ActionStyle.Cancel` | Dismisses the dialog |

---

## System

# Clipboard

Read from and write to the system clipboard.

## Copy

```tsx
import { Clipboard } from "@vicinae/api";

await Clipboard.copy("🍎 Apple");
```

Pass `concealed` to prevent the entry from being indexed by the clipboard manager (useful for secrets).

```tsx
await Clipboard.copy("secret-api-key", { concealed: true });
```

## Paste

Paste content into the frontmost application. Falls back to a regular copy if pasting isn't supported.

```tsx
import { Clipboard } from "@vicinae/api";

await Clipboard.paste("🍎");
```

## Read

Read the current clipboard content. Can contain text, HTML, or a file path.

```tsx
import { Clipboard } from "@vicinae/api";

const { text } = await Clipboard.read();
```

Or read just the text:

```tsx
const text = await Clipboard.readText();
```

## Clear

```tsx
import { Clipboard } from "@vicinae/api";

await Clipboard.clear();
```

## Content Types

`Clipboard.copy` and `Clipboard.paste` accept a string or a `Clipboard.Content` object:

```tsx
await Clipboard.copy({ html: "<b>Apple</b>", text: "Apple" });
await Clipboard.copy({ file: "/path/to/image.png" });
```

---

# Cache

An LRU disk cache for data that is expensive to fetch. Unlike `LocalStorage`, cache entries are evicted when the capacity / TTL is exceeded.

## Basic Usage

```tsx
import { Cache } from "@vicinae/api";

const cache = new Cache();

cache.set("fruits", JSON.stringify(["🍎", "🍌", "🍒"]));
const data = cache.get("fruits");
```

All methods are synchronous, no `await` needed.

## Expiration

Set a time-to-live in milliseconds, either globally or per key.

```tsx
import { Cache } from "@vicinae/api";

const cache = new Cache({ ttl: 60_000 });

cache.set("fresh", "data");
cache.set("stale-faster", "data", { ttl: 10_000 });
```

## Namespaces

Isolate cache data between commands of the same extension.

```tsx
import { Cache } from "@vicinae/api";

const cache = new Cache({ namespace: "my-command" });
```

If no namespace is specified, the default namespace is shared across all commands of the same extension.

## Subscribing to Changes

Get notified when cache data changes.

```tsx
import { Cache } from "@vicinae/api";

const cache = new Cache();

const unsubscribe = cache.subscribe((key, data) => {
  console.log(`${key} changed`);
});
```

## Other Methods

| Method | Description |
| --- | --- |
| `cache.has(key)` | Check existence without affecting LRU order |
| `cache.remove(key)` | Remove a single entry |
| `cache.clear()` | Remove all entries |
| `cache.isEmpty` | Whether the cache has any entries |

---

# Local Storage

Persistent key-value storage for extensions. Data persists across command runs and is never evicted as long as the extension remains installed.

Local storage data is stored in the internal Vicinae database, which will become fully encrypted in a future version.

## Store and Retrieve

```tsx
import { LocalStorage } from "@vicinae/api";

await LocalStorage.setItem("favoriteFruit", "🍎");

const fruit = await LocalStorage.getItem<string>("favoriteFruit");
```

## Remove

```tsx
import { LocalStorage } from "@vicinae/api";

await LocalStorage.removeItem("favoriteFruit");
```

## List All Items

```tsx
import { LocalStorage } from "@vicinae/api";

const items = await LocalStorage.allItems();
// { favoriteFruit: "🍎", count: 42 }
```

## Clear

Remove all stored items for this extension.

```tsx
import { LocalStorage } from "@vicinae/api";

await LocalStorage.clear();
```

## Supported Value Types

Values can be `string`, `number`, or `boolean`. More complex data needs to be serialized as a `string`.

Common approaches include stringifying JSON using `JSON.stringify` or encoding binary data as base64 using Node.js `Buffer`:

```ts
// store json data
const json = await res.json();
await LocalStorage.set('myData', JSON.stringify(json));

// store binary data
const blob = readFileSync('./my_icon.png').toString('base64');
await LocalStorage.set('icon', blob);
```

## LocalStorage or Cache?

Use LocalStorage over Cache if you:

* need full control over the lifetime of stored values (cache data can be evicted at any time)
* need to store sensitive user data such as API keys or secrets (the internal database is not yet encrypted, so this is a forward-looking best practice).

---

# Preferences

Read user-configured settings at runtime. See [Preferences](https://docs.vicinae.com/extensions/preferences) for how to declare them in the manifest.

## getPreferenceValues

```tsx
import { getPreferenceValues } from "@vicinae/api";

interface Preferences {
  apiKey: string;
  showDetails: boolean;
}

const { apiKey, showDetails } = getPreferenceValues<Preferences>();
```

## Opening Preferences

Navigate the user to the extension or command preferences in the settings window.

```tsx
import { openExtensionPreferences, openCommandPreferences } from "@vicinae/api";

await openExtensionPreferences();
await openCommandPreferences();
```

---

# Environment

Runtime information about the current extension, command, and Vicinae instance.

## Usage

```tsx
import { environment } from "@vicinae/api";

console.log(environment.extensionName);
console.log(environment.commandName);
console.log(environment.isDevelopment);
```

## Key Properties

| Property | Description |
| --- | --- |
| `extensionName` | Name of the extension from `package.json` |
| `commandName` | Name of the currently running command |
| `commandMode` | `"view"`, `"no-view"`, or `"menu-bar"` |
| `appearance` | `"light"` or `"dark"` |
| `isDevelopment` | Whether this is a development build |
| `assetsPath` | Absolute path to the extension's `assets/` directory |
| `supportPath` | Writable directory for extension data and files |

```tsx
import { environment } from "@vicinae/api";
import { readFileSync } from "fs";

const data = readFileSync(`${environment.supportPath}/data.json`, "utf-8");
```

## LaunchProps

Commands receive `LaunchProps` with the launch type, arguments, draft values, and launch context.

```tsx
import { LaunchProps, Detail } from "@vicinae/api";

export default function Command(props: LaunchProps<{ arguments: { query: string } }>) {
  return <Detail markdown={`You searched: ${props.arguments.query}`} />;
}
```

---

# Keyboard

Types and utilities for binding keyboard shortcuts to actions.

## Keyboard.Shortcut

A shortcut is a combination of a key and one or more modifiers.

```tsx
import { Action, Keyboard } from "@vicinae/api";

<Action
  title="Refresh"
  shortcut={{ key: "r", modifiers: ["cmd"] }}
  onAction={() => {}}
/>
```

## Common Shortcuts

Use `Keyboard.Shortcut.Common` for standard operations. These respect user-configured keybindings.

```tsx
import { Action, Keyboard } from "@vicinae/api";

<Action.CopyToClipboard
  title="Copy"
  content="🍎"
  shortcut={Keyboard.Shortcut.Common.Copy}
/>
```

| Shortcut | Name |
| --- | --- |
| `Keyboard.Shortcut.Common.Copy` | Copy |
| `Keyboard.Shortcut.Common.Save` | Save |
| `Keyboard.Shortcut.Common.Edit` | Edit |
| `Keyboard.Shortcut.Common.New` | New |
| `Keyboard.Shortcut.Common.Open` | Open |
| `Keyboard.Shortcut.Common.OpenWith` | Open With |
| `Keyboard.Shortcut.Common.Duplicate` | Duplicate |
| `Keyboard.Shortcut.Common.Refresh` | Refresh |
| `Keyboard.Shortcut.Common.Remove` | Remove |
| `Keyboard.Shortcut.Common.RemoveAll` | Remove All |
| `Keyboard.Shortcut.Common.Pin` | Pin |
| `Keyboard.Shortcut.Common.MoveUp` | Move Up |
| `Keyboard.Shortcut.Common.MoveDown` | Move Down |
| `Keyboard.Shortcut.Common.CopyDeeplink` | Copy Deeplink |
| `Keyboard.Shortcut.Common.CopyName` | Copy Name |
| `Keyboard.Shortcut.Common.CopyPath` | Copy Path |

## Modifiers

| Modifier | Key |
| --- | --- |
| `cmd` | Command |
| `ctrl` | Control |
| `opt` | Option / Alt |
| `shift` | Shift |

---

# OAuth

Built-in support for OAuth 2.0 PKCE flows, allowing extensions to authenticate with third-party services.

The OAuth implementation is still tied to Raycast services, as it was first implemented to support Raycast extensions. Native Vicinae methods will be proposed in the future.

## Setup

Create a PKCE client with your provider details.

```tsx
import { OAuth } from "@vicinae/api";

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "GitHub",
  providerIcon: "github.png",
  description: "Connect your GitHub account",
});
```

## Authorization Flow

```tsx
import { OAuth } from "@vicinae/api";

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "GitHub",
  providerIcon: "github.png",
});

const authRequest = await client.authorizationRequest({
  endpoint: "https://github.com/login/oauth/authorize",
  clientId: "your-client-id",
  scope: "repo user",
});

const { authorizationCode } = await client.authorize(authRequest);
// Exchange authorizationCode for tokens via your provider's token endpoint
```

## Token Storage

Store and retrieve tokens.

```tsx
await client.setTokens({
  accessToken: "gho_...",
  refreshToken: "ghr_...",
  expiresIn: 3600,
});

const tokens = await client.getTokens();
if (tokens?.isExpired()) {
  // refresh the token
}
```

## Redirect Methods

| Method | Description |
| --- | --- |
| `OAuth.RedirectMethod.Web` | Redirects through the **Raycast** website. A Vicinae equivalent will ship in the future. |
| `OAuth.RedirectMethod.App` | Uses `raycast://` app scheme |
| `OAuth.RedirectMethod.AppURI` | Uses `com.raycast:/` URI scheme |

---

# AI

Coming soon :)

---

# Utilities

System-level functions for opening files, running terminal commands, querying applications, and controlling the launcher window.

## open

Open a URL or file with the default application, or a specific one.

```tsx
import { open } from "@vicinae/api";

await open("https://vicinae.org");
await open("/path/to/file.pdf");
await open("/path/to/file.txt", "code");
```

## runInTerminal

Run a command in a new terminal window. The arguments are not interpreted by a shell.

```tsx
import { runInTerminal } from "@vicinae/api";

await runInTerminal(["journalctl", "--user", "-u", "vicinae", "-f"]);
```

To run a shell command, wrap it explicitly:

```tsx
await runInTerminal(["/bin/bash", "-c", "echo $HOME"], { hold: true });
```

### Options

| Option | Description |
| --- | --- |
| `hold` | Keep the terminal open after the command finishes |
| `workingDirectory` | Set the working directory |
| `appId` | Override the application ID for the terminal window |
| `title` | Override the window title |

Options are hints to the terminal emulator and may not be honored by all terminals. Vicinae follows the [xdg-terminal-exec](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/3/diffs) specification.

## showInFileBrowser

Reveal a file or folder in the system file browser.

```tsx
import { showInFileBrowser } from "@vicinae/api";

await showInFileBrowser("/path/to/file.txt");
await showInFileBrowser("/path/to/file.txt", { select: true });
```

## trash

Move files to the system trash.

```tsx
import { trash } from "@vicinae/api";

await trash("/path/to/file.txt");
await trash(["/path/to/a.txt", "/path/to/b.txt"]);
```

On Linux, Vicinae currently does not try to simulate a proper trash nor use any of the available ones (sometimes exposed by file managers). The files are immediately and permanently removed from the filesystem.

## Applications

Query installed applications on the system.

```tsx
import { getApplications, getDefaultApplication, getFrontmostApplication } from "@vicinae/api";

const apps = await getApplications();
const defaultApp = await getDefaultApplication("/path/to/file.pdf");
const frontmost = await getFrontmostApplication();
```

Each `Application` has `id`, `name`, `path`, and an optional `icon`.

The icon returned for an application, if any, should not be considered stable and should not be stored as-is. It is meant to be passed as an icon at runtime to any Vicinae API that accepts them.

## closeMainWindow

Close the launcher window. Useful after performing an action that doesn't need further user interaction.

```tsx
import { closeMainWindow } from "@vicinae/api";

await closeMainWindow();
```

## showHUD

Close the launcher window and show a brief heads-up message.

```tsx
import { showHUD } from "@vicinae/api";

await showHUD("Copied to clipboard!");
```

## popToRoot

Reset the navigation stack to the root view of the current command.

```tsx
import { popToRoot } from "@vicinae/api";

await popToRoot();
```

## getSelectedText

Get the currently selected text. Often combined with `Clipboard.paste` to replace the selected text with something else.

```tsx
import { getSelectedText, Clipboard } from "@vicinae/api";

const selected = await getSelectedText();
await Clipboard.paste(selected.toUpperCase());
```

---

# Window Management

Interact with application windows, workspaces, and screens.

## List Windows

```tsx
import { WindowManagement } from "@vicinae/api";

const windows = await WindowManagement.getWindows();

for (const win of windows) {
  console.log(win.title, win.application?.name, win.active);
}
```

## Focus a Window

```tsx
import { WindowManagement } from "@vicinae/api";

const windows = await WindowManagement.getWindows();
const browser = windows.find((w) => w.application?.name?.includes("firefox"));

if (browser) {
  await browser.focus();
}
```

## Active Window

```tsx
import { WindowManagement } from "@vicinae/api";

const active = await WindowManagement.getActiveWindow();
console.log(active.title);
```

## Workspaces

```tsx
import { WindowManagement } from "@vicinae/api";

const workspaces = await WindowManagement.getWorkspaces();
const active = await WindowManagement.getActiveWorkspace();
const windows = await WindowManagement.getWindowsOnActiveWorkspace();
```

## Screens

Get information about attached screens.

```tsx
import { WindowManagement } from "@vicinae/api";

const screens = await WindowManagement.getScreens();

for (const screen of screens) {
  console.log(screen.name, screen.make, screen.model, screen.bounds);
}
```

---

# File Search

Search for files on the user's system using Vicinae's built-in file index.

## Search

```tsx
import { FileSearch } from "@vicinae/api";

const results = await FileSearch.search("invoice");

for (const file of results) {
  console.log(file.name, file.path);
}
```

The search uses fuzzy filename matching. For example, a file named "example folder" matches queries like "fol exa" or "ex fold".

---

# Commands

Update metadata for the current command at runtime.

## updateCommandMetadata

Change the subtitle shown next to the command in Vicinae. Useful for displaying live data like counts or status.

```tsx
import { updateCommandMetadata } from "@vicinae/api";

await updateCommandMetadata({ subtitle: "12 fruits" });
```

Pass `null` to clear the custom subtitle and fall back to the one defined in `package.json`.

---