### Install Built Binaries with CMake

Source: https://docs.vicinae.com/build

Installs the built Vicinae binaries using CMake's install command. This example installs to a user-defined prefix, typically in the home directory.

```bash
sudo cmake --install build --prefix "$HOME/.local"
```

--------------------------------

### Start Vicinae Server

Source: https://docs.vicinae.com/quickstart/generic

Run this command to start the Vicinae server. This is the most basic way to get the server running.

```bash
vicinae server
```

--------------------------------

### Install Built Binaries with Make

Source: https://docs.vicinae.com/build

Installs the built Vicinae binaries to standard system directories using the 'make install' command. This requires superuser privileges.

```bash
sudo make install
```

--------------------------------

### Install Terra and Vicinae on Fedora

Source: https://docs.vicinae.com/install/repo

Install the Terra package repository, then install Vicinae.

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

--------------------------------

### Install Extension Dependencies

Source: https://docs.vicinae.com/extensions/create

Install the necessary dependencies for your newly created extension.

```bash
npm install
```

--------------------------------

### Install and Build Extension from Source

Source: https://docs.vicinae.com/install-extensions

Use these commands to install dependencies and build an extension after downloading its source code. No server restart is needed.

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

--------------------------------

### Install Build Dependencies on Ubuntu

Source: https://docs.vicinae.com/build

Installs necessary development tools and libraries for building Vicinae on Ubuntu.

```bash
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
```

--------------------------------

### User Configuration File Example

Source: https://docs.vicinae.com/config

Example of a user configuration file (~/.config/vicinae/settings.json) showing how to import other configuration files. Imported files are merged before the main user configuration.

```json
{
	"imports": [
		"base_config.json",
		"keybinds.json"
	],

	// remaining configuration...
}
```

--------------------------------

### Start Vicinae Server and Toggle

Source: https://docs.vicinae.com/quickstart/niri

Add this to your niri configuration to start the Vicinae server on startup and bind a shortcut to toggle it.

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

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

--------------------------------

### Quick Install Vicinae

Source: https://docs.vicinae.com/install/script

Run this command to perform a quick installation of Vicinae. It will download the latest AppImage and set up necessary files.

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

--------------------------------

### Install Vicinae with Custom Prefix

Source: https://docs.vicinae.com/install/script

Use the --prefix option with the installation script to install Vicinae to a custom location, such as your home directory.

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

--------------------------------

### Example Extension Manifest

Source: https://docs.vicinae.com/extensions/manifest

This is a complete example of an extension manifest file, showcasing common fields like name, title, description, icon, commands, and dependencies.

```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"
  }
}
```

--------------------------------

### Verify Vicinae Installation

Source: https://docs.vicinae.com/install/script

After installation, use this command to check the installed Vicinae version and build details.

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

--------------------------------

### Install Build Dependencies on Gentoo Linux

Source: https://docs.vicinae.com/build

Installs necessary development tools and libraries for building Vicinae on Gentoo Linux.

```bash
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
```

--------------------------------

### Add jaredallard's overlay and install Vicinae on Gentoo

Source: https://docs.vicinae.com/install/repo

Add a custom repository and sync it, then emerge the Vicinae package.

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

--------------------------------

### Enable COPR repository and install Vicinae on Fedora

Source: https://docs.vicinae.com/install/repo

Enable the Vicinae COPR repository and then install the Vicinae package using dnf.

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

--------------------------------

### Enable and start Vicinae systemd user service

Source: https://docs.vicinae.com/quickstart/cosmic

Use this command to immediately start the Vicinae server and ensure it runs on new COSMIC sessions. Requires systemd.

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

--------------------------------

### Install Build Dependencies on Arch Linux

Source: https://docs.vicinae.com/build

Installs necessary development tools and libraries for building Vicinae on Arch Linux.

```bash
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
```

--------------------------------

### Start Extension in Development Mode

Source: https://docs.vicinae.com/extensions/create

Run your extension in development mode. Vicinae must be running for this command to work.

```bash
npm run dev
```

--------------------------------

### Install Vicinae on Bazzite using Terra

Source: https://docs.vicinae.com/install/repo

For Bazzite users, enable the Terra repository and install Vicinae using rpm-ostree.

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

--------------------------------

### Install Vicinae SDK for Raycast Extensions

Source: https://docs.vicinae.com/extensions/debug-raycast

Install the necessary Vicinae SDK packages within the extension's source tree to enable development mode.

```bash
npm install
npm install --save-dev @vicinae/api
```

--------------------------------

### Install Vicinae on Fedora Atomic using Terra

Source: https://docs.vicinae.com/install/repo

Download the Terra repository configuration and install Vicinae using rpm-ostree.

```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
```

--------------------------------

### Launch a Specific Entrypoint

Source: https://docs.vicinae.com/deeplinks

Activate the primary action of an entrypoint by specifying its provider and name. For example, to open clipboard history.

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

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

--------------------------------

### Minimal TOML Theme Example

Source: https://docs.vicinae.com/theming/getting-started

A basic TOML theme configuration defining metadata and core colors. This example sets a dark variant and inherits from 'vicinae-dark'.

```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"
```

--------------------------------

### React/TypeScript List Extension Example

Source: https://docs.vicinae.com/extensions/introduction

This snippet demonstrates how to create a list view in Vicinae using the React/TypeScript API. It includes sections, list items with details, and actions like copying to the clipboard. Ensure you have the '@vicinae/api' package installed and data available in './data'.

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

export default function FruitList() {
	return (
		<List isShowingDetail searchBarPlaceholder={'Search fruits...'}>
			<List.Section title="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.Section>
		</List>
	);
}
```

--------------------------------

### Install Vicinae on Arch Linux (AUR)

Source: https://docs.vicinae.com/install/repo

Use an AUR helper like 'yay' to install the prebuilt binary version of Vicinae from the Arch User Repository.

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

--------------------------------

### Configure Vicinae settings and extensions

Source: https://docs.vicinae.com/nixos

Declaratively configure Vicinae's behavior and enable extensions using Home Manager. This example sets various UI and functional options, including theme, font, and specific extensions.

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

services.vicinae = {
  enable = true;
  systemd = {
    enable = true;
    autoStart = true; # default: false
    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
  ];
};
```

--------------------------------

### Configure Vicinae extension providers

Source: https://docs.vicinae.com/nixos

Configure specific Vicinae extensions declaratively by defining their provider settings. This example shows how to set preferences for the '@knoopx/nix-0' provider, including a GitHub token.

```nix
{
#...
  services.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";
        };
      };
    };
  };
}
```

--------------------------------

### Enable Vicinae Service with uwsm

Source: https://docs.vicinae.com/quickstart/hyprland

If using uwsm to manage Hyprland, enable and start the vicinae systemd service instead of using 'exec-once'.

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

--------------------------------

### Set Capabilities for vicinae-input-server

Source: https://docs.vicinae.com/snippets

Manually set kernel capabilities for the vicinae-input-server if it fails to start due to insufficient privileges. This is typically handled by the package manager.

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

--------------------------------

### Get Default Vicinae Configuration

Source: https://docs.vicinae.com/config

Run this command to obtain the default configuration for Vicinae.

```bash
vicinae config default
```

--------------------------------

### Install Build Dependencies on Fedora

Source: https://docs.vicinae.com/build

Installs necessary development tools and libraries for building Vicinae on Fedora. Note that cmark-gfm requires a COPR repository.

```bash
dnf install -y \
    qt6-qtbase-devel \
    qt6-qtsvg-devel \
    qt6-qtbase-private-devel \
    qt6-qtwayland-devel \
    layer-shell-qt-devel \
    libqalculate-devel \
    minizip-devel \
    rapidfuzz-cpp-devel \
    qtkeychain-qt6-devel \
    openssl-devel \
    wayland-devel \
    glibc-static \
    libstdc++-static \
    zlib-devel \
    zlib-static \
    abseil-cpp-devel \
    protobuf-devel \
    libicu-devel \
    cmark-gfm-devel
# cmark-gfm requires a copr (https://copr.fedoraincloud.org/coprs/quadratech188/cmark-gfm/)
```

--------------------------------

### Configure sops-nix Templates for Vicinae

Source: https://docs.vicinae.com/nixos

Set up sops-nix secrets and templates in your Nix configuration. This example defines a template for Vicinae's settings, injecting the GitHub token securely.

```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; 
              };
            };
          };
        };
      };
    };
  };
}
```

--------------------------------

### Bind Keyboard Shortcut to Toggle Vicinae

Source: https://docs.vicinae.com/deeplinks

Example of how to bind a keyboard shortcut in Hyprland to toggle the Vicinae window. It's recommended to use the `vicinae` binary for direct execution.

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

--------------------------------

### Toggle Vicinae Window

Source: https://docs.vicinae.com/quickstart/generic

Use this command to show or hide the Vicinae window after the server has been started. This provides a quick way to interact with the application.

```bash
vicinae toggle
```

--------------------------------

### Python Script Example with Vicinae Directives

Source: https://docs.vicinae.com/scripts/getting-started

This is a basic Python script demonstrating the required Vicinae directives for title, schema version, and output mode. Ensure the script has executable permissions and a correct shebang line.

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

print("Hello world!")
```

--------------------------------

### NixOS Configuration with Vicinae module

Source: https://docs.vicinae.com/nixos

Integrate Vicinae into your NixOS system configuration by including its default NixOS module. This example shows how to add Vicinae to your system and home-manager configurations.

```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];
    };
  };
}
```

--------------------------------

### Run Vicinae with nix shell

Source: https://docs.vicinae.com/nixos

Execute Vicinae directly without a full installation using a nix shell. This is useful for testing or temporary usage.

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

--------------------------------

### Pushing and Popping Views with useNavigation

Source: https://docs.vicinae.com/extensions/view-command

The `useNavigation` hook allows a view command to push new views onto the navigation stack or pop the current view. This example demonstrates pushing a `ListView` and popping it.

```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>
			}
		/>
	);
}
```

--------------------------------

### Import sops-nix Template into Vicinae Settings

Source: https://docs.vicinae.com/nixos

Import the generated sops-nix template file into Vicinae's settings. Ensure the correct sops configuration path is used based on your Nix setup (e.g., `config.sops` or `nixosConfig.sops`).

```nix
{ ... }:
{
  services.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];
  };
}
```

--------------------------------

### Display All Theme Commands

Source: https://docs.vicinae.com/theming/cli-tools

Run this command to see all available subcommands and options for theme management.

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

--------------------------------

### Build AppImage

Source: https://docs.vicinae.com/build-appimage

After running the build environment, use these commands to clean the build tree and then build the AppImage. Ensure the build tree is clean before proceeding.

```bash
make clean
make appimage
```

--------------------------------

### Define CMake Build Options

Source: https://docs.vicinae.com/build

Demonstrates how to define build options in CMakeLists.txt for features like LTO, symbol stripping, and using system libraries.

```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)
```

--------------------------------

### Generate New Theme Template

Source: https://docs.vicinae.com/theming/cli-tools

Creates a complete theme template with all color keys and documentation, outputting it to stdout. Redirect the output to a file to save the template.

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

--------------------------------

### Uninstall Vicinae

Source: https://docs.vicinae.com/install/script

Execute the installation script with the --uninstall argument to remove Vicinae from your system.

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

--------------------------------

### List available clipboard offers

Source: https://docs.vicinae.com/clipboard

This command lists the different formats (offers) available for the current clipboard selection, showing the variety of data representations.

```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
```

--------------------------------

### Dropdown Preference with Data

Source: https://docs.vicinae.com/extensions/manifest

An example of a preference object of type 'dropdown', which includes a 'data' field to specify the available options and their values.

```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"
	}
  ]
}
```

--------------------------------

### Hyprland Main Configuration with Vicinae

Source: https://docs.vicinae.com/quickstart/hyprland-lua

Add this to your Hyprland configuration to enable Vicinae's server, toggle functionality, and apply visual rules like blur and animation disabling.

```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,
})

```

--------------------------------

### Select Theme via CLI

Source: https://docs.vicinae.com/theming/getting-started

Use the Vicinae CLI to set a new theme. The theme ID corresponds to the filename of the TOML theme file.

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

--------------------------------

### Bind Custom Vicinae Command

Source: https://docs.vicinae.com/quickstart/niri

Create a custom binding in your niri configuration to open specific vicinae commands via deeplinks. This example opens the clipboard history.

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

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

--------------------------------

### Filter Root Search by Provider

Source: https://docs.vicinae.com/deeplinks

Restrict search results to a specific provider using the `vicinae://launch/<provider>` deeplink format. For example, to search only power commands.

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

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

--------------------------------

### Combine Opacity and Lightness Modifications

Source: https://docs.vicinae.com/theming/advanced-features

Create a color that is both darker and semi-transparent by combining 'darker' and 'opacity' properties in a complex color object. This example defines a subtle accent color.

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

--------------------------------

### Typical Vicinae Extension Directory Structure

Source: https://docs.vicinae.com/extensions/file-structure

Illustrates the standard layout of files and directories within a Vicinae extension project.

```bash
my-first-extension
    ├── assets
    │   └── extension_icon.webp
    ├── package.json
    ├── package-lock.json
    ├── README.md
    ├── src
    │   └── my-first-command.tsx
    └── tsconfig.json
```

--------------------------------

### dmenu mode wallpaper picker with quick look

Source: https://docs.vicinae.com/dmenu

Use this snippet to select a wallpaper from a list of image files, utilizing the quick look feature for previews.

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

--------------------------------

### Generate Vicinae Theme from Image

Source: https://docs.vicinae.com/theming/matugen

Execute this command to generate a Vicinae theme from a specified image file using matugen. This process extracts colors, creates a theme, saves it, and applies it.

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

--------------------------------

### Disable Telemetry Command

Source: https://docs.vicinae.com/telemetry

This command contacts the Vicinae server to delete telemetry data and disable telemetry collection. It should be used to request immediate and permanent removal of your installation's telemetry data.

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

--------------------------------

### Generic Release Build with Make

Source: https://docs.vicinae.com/build

Builds a generic, unoptimized release version of Vicinae using the 'make' command. This is suitable for general use when LTO is not required.

```bash
make release
```

--------------------------------

### Detect and Avoid Circular Color References

Source: https://docs.vicinae.com/theming/advanced-features

Circular references occur when colors directly or indirectly reference each other, preventing theme loading. This example shows a simple circular reference between background and foreground colors.

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

--------------------------------

### Build AppImage Build Environment Locally

Source: https://docs.vicinae.com/build-appimage

Build the AppImage build environment Docker image locally. This process can be time-consuming and is generally recommended only if the DockerHub image cannot be used.

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

--------------------------------

### Modify Color Lightness

Source: https://docs.vicinae.com/theming/advanced-features

Adjust the lightness of a color using 'darker' or 'lighter' properties within a complex color object. This example darkens the blue accent for the border and then lightens it for the input border focus.

```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 }
```

--------------------------------

### Create a custom keyboard shortcut to toggle Vicinae

Source: https://docs.vicinae.com/quickstart/kde

Configure a custom keyboard shortcut in KDE settings to toggle the Vicinae window. Ensure the Vicinae server is running for this to work.

```bash
vicinae
```

--------------------------------

### Define a Complex Color Value with Opacity

Source: https://docs.vicinae.com/theming/advanced-features

Use complex color objects to define colors with specific properties like opacity. This example sets the border color to a blue accent with 50% opacity.

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

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

--------------------------------

### Configure Matugen for Vicinae

Source: https://docs.vicinae.com/theming/matugen

Add this TOML configuration to your matugen config file to set up wallpaper detection and theme generation for Vicinae. The post_hook ensures the theme is applied automatically.

```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'
```

--------------------------------

### Set Emoji Font Environment Variable

Source: https://docs.vicinae.com/emoji

Override the default emoji font by setting the EMOJI_FONT environment variable to your desired font family before starting the Vicinae server. If the font family is invalid, a warning will be issued.

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

--------------------------------

### Home Manager configuration for Vicinae service

Source: https://docs.vicinae.com/nixos

Enable and configure the Vicinae systemd service using Home Manager. This snippet shows how to enable the service, set it to auto-start, and configure environment variables.

```nix
{ 
  # ...

  services.vicinae = {
    enable = true; # default: false
    systemd = {
      enable = true; # default: false
      autoStart = true; # default: false
      environment = {
        USE_LAYER_SHELL = 1;
      };
    };
  };
}
```

--------------------------------

### Create a Deeplink Shortcut

Source: https://docs.vicinae.com/quickstart/gnome

Sets up a custom keyboard shortcut to open a specific Vicinae command using deeplinks. This allows for quick access to predefined actions.

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

--------------------------------

### Adjust scrolling velocity in Vicinae

Source: https://docs.vicinae.com/faq

Override the QT_QUICK_FLICKABLE_WHEEL_DECELERATION environment variable to adjust scrolling speed. A lower value increases scrolling velocity. Vicinae sets a slightly lower default starting from v0.20.4 if the variable is not specified.

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

--------------------------------

### Download Vicinae Matugen Template

Source: https://docs.vicinae.com/theming/matugen

Use this bash command to download the official Vicinae theme template for matugen. This template is necessary for matugen to generate compatible Vicinae themes.

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

--------------------------------

### Launch Entrypoint with Toggle Behavior

Source: https://docs.vicinae.com/deeplinks

Append `toggle=true` to a launch deeplink to automatically close the window if it's already open, providing toggle functionality.

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

--------------------------------

### Optimized Release Build with Make

Source: https://docs.vicinae.com/build

Builds an optimized release version of Vicinae using 'make host-optimized'. This command enables system-specific optimizations for maximum performance.

```bash
make host-optimized
```

--------------------------------

### Vicinae System Telemetry Payload

Source: https://docs.vicinae.com/telemetry

This JSON object represents the system information collected by Vicinae upon startup. It includes details such as the installation's unique user ID, Vicinae version, display protocol, architecture, operating system, and screen configurations. This data is sent once every 24 hours to help track daily active users and version upgrade rates.

```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"
}
```

--------------------------------

### Clone Vicinae Repository

Source: https://docs.vicinae.com/build

Use this command to clone the Vicinae repository and navigate into the source directory. This is the first step for building from source.

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

--------------------------------

### Generic Release Build with CMake

Source: https://docs.vicinae.com/build

Configures and builds a generic release version of Vicinae using CMake. This command sets up the build directory and then initiates the build process.

```bash
cmake -G Ninja -B build
cmake --build build
```

--------------------------------

### List Clipboard Offers

Source: https://docs.vicinae.com/clipboard

This command lists the available MIME types for a clipboard selection, useful for understanding what data is available.

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

--------------------------------

### Add Vicinae to Hyprland Configuration

Source: https://docs.vicinae.com/quickstart/hyprland

Add this to your Hyprland configuration file to enable Vicinae. Exclude the 'exec-once' line if using uwsm.

```ini
# ~/.config/hypr/hyprland.conf

exec-once = vicinae server # exclude this if using uwsm

# use whatever shortcut floats your boat
bind = $mainMod, Space, exec, vicinae toggle

# old rule syntax (Hyprland < 0.53)
# blur
# layerrule = blur, vicinae
# layerrule = ignorealpha 0, vicinae
# disable animation for vicinae only
# layerrule = noanim, vicinae

# named rule syntax (Hyprland 0.53+)
# blur
layerrule {
    name = vicinae-blur
    blur = on
    ignore_alpha = 0
    match:namespace = vicinae
}

# disable animation for vicinae only
layerrule {
    name = vicinae-no-animation
    no_anim = on
    match:namespace = vicinae
}

# anonymous rule syntax (Hyprland 0.53+)
# layerrule = blur on, ignore_alpha 0, match:namespace vicinae
# layerrule = no_anim on, match:namespace vicinae

```

--------------------------------

### View Command Entrypoint Implementation

Source: https://docs.vicinae.com/extensions/view-command

The entrypoint file for a view command must export a React component as the default export. This component will be rendered when the command is launched.

```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>
			}
		/>
	);
}
```

--------------------------------

### Launch Entrypoint with Fallback Text

Source: https://docs.vicinae.com/deeplinks

Use the `fallbackText` query parameter to set a default search text when launching a command via deeplink.

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

--------------------------------

### dmenu mode from file input

Source: https://docs.vicinae.com/dmenu

Use this snippet to generate a menu from a list of options stored in a file.

```bash
vicinae dmenu --placeholder "Select option" < options.txt
```

--------------------------------

### Use vicinae package from nixpkgs

Source: https://docs.vicinae.com/nixos

Alternatively, use the vicinae package directly from nixpkgs if you prefer it to be built by Hydra and potentially be out of date. This configures the service to use the nixpkgs version.

```nix
{ pkgs, ... }:
{
  services.vicinae = {
    package = pkgs.vicinae;
  };
}
```

--------------------------------

### View Theme Search Paths

Source: https://docs.vicinae.com/theming/cli-tools

Displays the directories where Vicinae searches for theme files, listed in order of precedence. This helps understand how themes are loaded and shadowed.

```bash
vicinae theme paths
```

--------------------------------

### Run Raycast Extension in Development Mode

Source: https://docs.vicinae.com/extensions/debug-raycast

Use the Vicinae CLI to run a Raycast extension in development mode. Ensure you are using `@raycast/api` exports for debugging.

```bash
npx vici develop
```

--------------------------------

### Launch Emoji Picker Command

Source: https://docs.vicinae.com/emoji

To use the emoji picker, launch the 'Search Emojis and Symbols' command via the specified URI.

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