<div align="center" style="text-align:center; border-radius:10px;"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg"> <img alt="sherlock logo" height="250" src="assets/logo-light.svg"> </picture>

<picture> <img alt="application screenshot" width="100%" style="border-radius: 10px;" src="assets/mockup.png"> </picture>

</div>

Sherlock is a lightweight and efficient application launcher built with Rust and GTK4. It allows you to quickly launch your favorite applications with a user-friendly interface, providing a fast and highly-configurable way to search, launch, and track application usage. <br>

Quick Links

• Documentation: Sherlock's documentation
• CONTRIBUTING.md: Please read this before submitting a PR.

Additional Plugins

• sherlock-wiki: allows you to search Wikipedia from within Sherlock using the bulk_text launcher.
• sherlock-confetti: A shader-based animation covering your entire screen.
• sherlock-dict: lookup word definitions from within Sherlock.
• sherlock-clipboard: A way for you to display cliphist history in sherlock <br><br>

[!CAUTION] This app is/was developed on Arch Linux with the Hyprland tiling window manager in mind. It may cause errors or won't function on your system. If so, please let me know in the issues, I will try my best to resolve it.

---

Table of Contents

• Features
• Getting Started
  • Dependencies
  • Installation
    • Arch Linux
    • From Source
    • Debian
    • Nix
  • Post Installation
    • Config Setup
    • Keybind Setup

---

<br>

Features

🔧 Style Customization

• Fully customize the look and feel of the launcher.
• Modify themes and visual elements to match your preferences

🛠️ Custom Commands

• Define your own commands and extend the functionality of the launcher.
• Add new features or workflows tailored to your specific needs.

🚀 Fallbacks

• Configure fallback behaviours for various commands and operations.
• Ensure a smooth experience even when certain commands fail or are unavailable

🖼️ Application Aliases and Customization

• Assign aliases to your applications for better looks and quicker access.
• Assign custom icons to your applications for a personalized touch.
• Hide apps that you don't use and don't want to clutter up your launcher.

🌐 Async Widget

• Use the async widget to send API requests and display their responses directly in the launcher.
• Great for integrating live data or external tools into your workflow.

🎵 Spotify/Music Player Widget

<div align="center" style="text-align:center; border-radius:10px;"> <picture> <img alt="music-launcher" width="100%" src="docs/assets/MprisTile.svg"> </picture> </div> <br>

• Show your currently playing song or video

📅 Teams Events Launcher

• Use the Teams Event Launcher to easily join upcoming Microsoft Teams meetings

🔍 Category-Based Search

• Type the launcher alias and space bar to only search within a specific category of commands.
• Categories are fully configurable, allowing you to customize search scopes.
• Use the category launcher to show a group for additional subcommands
• Start Sherlock with the --sub-menu flag to only search within a category.

⌨️ Shortcuts

• Use modkey + number shortcuts to quickly launch a command or app without having to scroll.
• Configure custom key binds for navigation

📁 Context menu

• A customizable context menu for additional application/launcher actions. For example opening a private browser window
• Extend or overwrite existing actions from your sherlock_alias.json file or create custom ones for your commands

🌞 Weather widget

<div align="center" style="text-align:center; border-radius:10px;"> <picture> <img alt="weather-launcher" width="100%" src="docs/assets/WeatherWidget.svg"> </picture> </div> <br>

• Show the weather in your specified location

---

<br><br>

Getting Started

1. Dependencies

To run the Sherlock Launcher, ensure the following dependencies are installed:

• gtk4 - Gtk4 Documentation
• gtk-4-layer-shell - Gtk4 Layer Shell
• dbus - (Used to get currently playing song)
• openssl - (Used for retrieving Spotify album art)
• libssl-dev
• libsqlite3-dev

Additionally, if you're building from source, you will need:

• rust - How to install rust
• git - How to install git <br><br>

2. Installation

<ins>Arch Linux</ins>

If you're using Arch Linux, you can install the pre-built binary package with the following command:

yay -S sherlock-launcher-bin

Or install the community-maintained git build with the following command:

yay -S sherlock-launcher-git

<ins>From Source</ins>

To build Sherlock Launcher from source, follow these steps.<br> Make sure you have the necessary dependencies installed:

• rust - How to install rust
• git - How to install git
• gtk4 - Gtk4 Documentation
• gtk-4-layer-shell - Gtk4 Layer Shell
• dbus - (Used to get currently playing song)
• libsqlite3-dev
• librsvg
• gdk-pixbuf2

1. Clone the repository:

   git clone https://github.com/skxxtz/sherlock.git
   cd sherlock
   

2. Install necessary Rust dependencies:

   Build the project using the following command:

   cargo build --release
   

3. Install the binary:

   After the build completes, install the binary to your system:

   sudo cp target/release/sherlock /usr/local/bin/
   

4. (Optional) Remove the build directory:

   You can optionally remove the source code directory.

   rm -rf /path/to/sherlock
   

<ins>Build Debian Package</ins>

To build a .deb package directly from the source, follow these steps:<br> Make sure you have the following dependencies installed:

• rust - How to install rust
• git - How to install git
• gtk4 - Gtk4 Documentation
• gtk-4-layer-shell - Gtk4 Layer Shell

1. Install the cargo-deb tool:

   First, you need to install the cargo-deb tool, which simplifies packaging Rust projects as Debian packages:

   cargo install cargo-deb
   

2. Build the Debian package:

   After installing cargo-deb, run the following command to build the .deb package:

   cargo deb
   

   This will create a .deb package in the target/debian directory.

3. Install the generated .deb package:

   Once the package is built, you can install it using:

   sudo dpkg -i target/debian/sherlock-launcher_*_amd64.deb
   

   You can use tab-completion to auto complete the exact file name.

<br><br>

<ins>Nix</ins>

Non-Flakes Systems

Sherlock is available in nixpkgs/unstable as sherlock-launcher. If you're installing it as a standalone package you'll need to do the config setup yourself.

Flakes & Home-Manager

A module for Sherlock is available in home manager. You can find it's configuration here. If you want to use the latest updates and module options, follow the steps below.

<details> <summary><strong>Home-Manager Example Configuration</strong></summary>

Add the following your inputs of flake.nix if you want to use the latest upstream version of sherlock.

sherlock = {
    url = "github:Skxxtz/sherlock";
    inputs.nixpkgs.follows = "nixpkgs";
};

Home-Manager config:

programs.sherlock = {
  enable = true;

  # to run sherlock as a daemon
  systemd.enable = true;

  # If wanted, you can use this line for the _latest_ package. / Otherwise, you're relying on nixpkgs to update it frequently enough.
  # For this to work, make sure to add sherlock as a flake input!
  # package = inputs.sherlock.packages.${pkgs.system}.default;

  # config.toml
  settings = {};

  # sherlock_alias.json
  aliases = {
    vesktop = { name = "Discord"; };
  };

  # sherlockignore
  ignore = ''
    Avahi*
  '';

  # fallback.json
  launchers = [
    {
      name = "Calculator";
      type = "calculation";
      args = {
        capabilities = [
          "calc.math"
          "calc.units"
        ];
      };
      priority = 1;
    }
    {
      name = "App Launcher";
      type = "app_launcher";
      args = {};
      priority = 2;
      home = "Home";
    }
  ];

  # main.css
  style = /* css */ ''
    * {
      font-family: sans-serif;
    }
  '';
};

</details>

Flakes without Home-Manager

To install the standalone package, add sherlock.packages.${pkgs.system}.default to environment.systemPackages/home.packages. You will need to create the configuration files yourself, see below.

3. Post Installation

**Config Setu