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:

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:

xdg-open vicinae://toggle

Browsers can also execute custom url schemes, with a few caveats. If Vicinae is currently running, clicking this link 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:

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:

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

For instance, this is how to open the clipboard history command using a deeplink:

vicinae://launch/clipboard/history

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

Pass fallback text to command

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

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.

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:

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:

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:

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

Set theme

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

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://.