3timeslazy/nix-search-tv

---

3timeslazy/nix-search-tv.json

{
  "createdAt": "2025-01-29T09:30:56Z",
  "defaultBranch": "main",
  "description": "Fuzzy search for Nix packages.",
  "fullName": "3timeslazy/nix-search-tv",
  "homepage": "",
  "language": "Go",
  "name": "nix-search-tv",
  "pushedAt": "2025-11-23T15:38:30Z",
  "stargazersCount": 169,
  "topics": [
    "cli",
    "fzf",
    "nix",
    "nixos",
    "search",
    "television"
  ],
  "updatedAt": "2025-11-24T12:10:57Z",
  "url": "https://github.com/3timeslazy/nix-search-tv"
}

nix-search-tv

Fuzzy search for NixOS packages.

---

Installation

Nix Package

environment.systemPackages = [ nix-search-tv ]

Flake

There are many ways how one can install a package from a flake, below is one:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nix-search-tv.url = "github:3timeslazy/nix-search-tv";
  };

  outputs = {
    nixpkgs,
    nix-search-tv,
    ...
  }: {
    nixosConfigurations.system = nixpkgs.lib.nixosSystem {
      modules = [
        {
          environment.systemPackages = [
            nix-search-tv.packages.x86_64-linux.default
          ];
        }
      ];
    };
  };
}

Usage

nix-search-tv does not do the search by itself, but rather integrates with other general purpose fuzzy finders, such as television and fzf

Television

Add nix.toml file to your television cables directory with the content below:

[metadata]
name = "nix"
requirements = ["nix-search-tv"]

[source]
command = "nix-search-tv print"

[preview]
command = "nix-search-tv preview {}"

or use the Home Manager option:

programs.nix-search-tv.enableTelevisionIntegration = true;

fzf

The most straightforward integration might look like:

alias ns="nix-search-tv print | fzf --preview 'nix-search-tv preview {}' --scheme history"

[!NOTE] No matter how you use nix-search-tv with fzf, it’s better to add --scheme history. That way, the options will be sorted, which makes the search experience better

More advanced integration might be found here in [nixpkgs.sh]!(./nixpkgs.sh). It is the same search but with the following shortcuts:

• Search only Nixpkgs or Home Manager
• Open package code declaration or homepage
• Search GitHub for snippets with the selected package/option
• And more

You can install it like:

let
  ns = pkgs.writeShellScriptBin "ns" (builtins.readFile ./path/to/nixpkgs.sh);
in {
  environment.systemPackages = [ ns ]
}

Configuration

By default, the configuration file is looked at $XDG_CONFIG_HOME/nix-search-tv/config.json

{
  // What indexes to search by default
  //
  // default:
  //   linux: [nixpkgs, "home-manager", "nur", "nixos"]
  //   darwin: [nixpkgs, "home-manager", "nur", "darwin"]
  "indexes": ["nixpkgs", "home-manager", "nur"],

  // How often to look for updates and run
  // indexer again
  //
  // default: 1 week (168h)
  "update_interval": "3h2m1s",

  // Where to store the index files
  //
  // default: $XDG_CACHE_HOME/nix-search-tv
  "cache_dir": "path/to/cache/dir",

  // Whether to show the banner when waiting for
  // the indexing
  //
  // default: true
  "enable_waiting_message": true,

  // More about experimental below
  "experimental": {
    "render_docs_indexes": {
      "plasma": "https://nix-community.github.io/plasma-manager/options.xhtml",
    },
    "options_file": {
      "agenix": "<path to options.json>",
    },
  },
}

Searchable package registries

Builtin

• Nixpkgs
• Home Manager
• NixOS
• Darwin
• NUR

Custom

Parse HTML

nix-search-tv can parse a documentation HTML page and extract options from it. How to tell if a page can be parsed? To understand that, check the links in the example below and if the documentation page looks exactly like one of them, it probably can be parsed.

{
  "render_docs_indexes": {
    // https://github.com/nix-community/plasma-manager
    "plasma": "https://nix-community.github.io/plasma-manager/options.xhtml",
  },
}

Parse options.json file

The point of this setting is to generate the options file at nix build time and point nix-search-tv to them. Internally, the tool compares previous and the new path and only re-indexes it if the path has changes.

{
  "options_file": {
    // https://github.com/ryantm/agenix
    "agenix": "<path to built options.json>",

    // https://jovian-experiments.github.io/Jovian-NixOS/index.html
    "jovian": "<path to built options.json>",
  },
}

Here’s one way to generate the options.json files for agenix and nixvim using unf and home-manager:

flake.nix

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    agenix.url = "github:ryantm/agenix";
    nixvim.url = "github:nix-community/nixvim";

    unf = {
      url = "git+https://git.atagen.co/atagen/unf";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    nixpkgs,
    home-manager,
    ...
  } @ inputs : let
    # It's not required to use `unf`, but even though
    # it brings some dependencies, I use it because its easy.
    mkOpts = system: module:
      inputs.unf.lib.json {
        inherit self;
        pkgs = nixpkgs.legacyPackages.${system};

        # not all modules can be evaluated easily. If your module
        # does not evaluate, try checking this NüschtOS file:
        #   https://github.com/NuschtOS/search.nuschtos.de/blob/main/flake.nix
        modules = [module];
      };
  in {
    nixosConfigurations.hostname = nixpkgs.lib.nixosSystem rec {
      system = "x86_64-linux";
      modules = [
        home-manager.nixosModules.home-manager
        {
          # extraSpecialArgs is used here to pass the options files
          # that depend on the flake inputs to home-manager modules,
          # where configuration files are usually defined.
          home-manager.extraSpecialArgs = {
            inherit inputs;

            agenixOptions = mkOpts system inputs.agenix.nixosModules.default;

            # nixvim provides an options.json file already
            nixvimOptions = inputs.nixvim.packages.${system}.options-json + /share/doc/nixos/options.json
          };
        }
      ];
    };
  };
}

# home.nix
{
  pkgs,
  lib,
  ...
} @ args : {
  xdg.configFile."nix-search-tv/config.json".text = builtins.toJSON {
    experimental = {
      options_file = {
        agenix = "${args.agenixOptions}";
        nixvim = "${args.nixvimOptions}";
      };
    };
  };

  # or, with home-manager
  programs.nix-search-tv = {
    enable = true;
    settings = {
      experimental.options_file = {
        agenix = "${args.agenixOptions}";
        nixvim = "${args.nixvimOptions}";
      };
    };
  };
}

Credits

This project was inspired and wouldn’t exist without work done by nix-search contributors.