fh: the CLI for FlakeHub

Last week, we released FlakeHub, a new platform for publishing, discovering, and using Nix flakes. We’ve been extremely pleased with the initial response: as of this post, more than 60 organizations have published a total of over 110 flakes to FlakeHub, and many Nix users have already incorporated the platform into their day-to-day workflows.

Although we’re happy with the web UI for FlakeHub, we know that many workflows will require more programmatic access to the platform. And so today we’re announcing the initial release of fh, the CLI for FlakeHub. To give an analogy, fh serves the same role for FlakeHub that the gh CLI serves for GitHub.

Getting started

First off, you’ll need Nix 2.17 or above to use fh. Check out the FlakeHub docs for information on how to upgrade.

Once you have a compatible version of Nix, there are several ways to get started. You can start a shell session with it installed using nix shell:

nix shell "https://api.flakehub.com/f/DeterminateSystems/fh/*.tar.gz"

You can also add it to a Nix development environment as in this flake.nix:

{
  inputs = {
    nixpkgs.url = "https://api.flakehub.com/f/NixOS/nixpkgs/0.2305.*.tar.gz";
    fh.url = "https://api.flakehub.com/f/DeterminateSystems/fh/0.1.*.tar.gz";
  };

  outputs = { self, nixpkgs, fh, .. } @ inputs:
    let
      supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
      forEachSupportedSystem = f: nixpkgs.lib.genAttrs supportedSystems (system: f {
        inherit system;
        pkgs = import nixpkgs { inherit system; };
      });
    in
    {
      devShells = forEachSupportedSystem ({ pkgs, system }: {
        default = pkgs.mkShell {
          packages = [
            fh.packages.${system}.fh
          ];
        };
      });
    };
}

To install it fh in your home environment, we recommend using Home Manager.

Commands

fh add

fh add adds a FlakeHub dependency to a flake. Let’s say that you’ve defined a flake in flake.nix in the current directory:

{
  inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2305.*.tar.gz";

  outputs = { self, nixpkgs }: {
    # Outputs here
  };
}

This command would add the ipetkov/crane flake:

fh add ipetkov/crane

The resulting flake.nix:

{
  inputs.crane.url = "https://flakehub.com/f/ipetkov/crane/0.13.1.tar.gz";
  inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2305.*.tar.gz";

  outputs = { self, nixpkgs, crane }: {
    # Outputs here
  };
}

fh add queries FlakeHub to find the most recent version of that input (in this case 0.13.1 for ipetkov/crane).

You can also use fh add with non-FlakeHub flake references. Some examples:

fh add github:NixOS/patchelf
fh

fh list

fh list has three subcommands that are useful for getting a general idea of what’s on FlakeHub right now:

• fh list flakes lists all the publicly listed flakes on FlakeHub
• fh list orgs lists all the publicly listed organizations on FlakeHub
• fh list releases <flake> lists all the releases of a flake on FlakeHub. Try fh list releases tailscale/tailscale, for example.

fh search

fh search enables you to search FlakeHub’s Algolia index of flakes using an arbitrary string query. Here’s an example:

fh search rust

That returns this table:

+---------------------------------------------------------------------------------+
| Flake                      FlakeHub URL                                         |
+---------------------------------------------------------------------------------+
| astro/deadnix              https://flakehub.com/flake/astro/deadnix             |
| carlthome/ml-runtimes      https://flakehub.com/flake/carlthome/ml-runtimes     |
| ipetkov/crane              https://flakehub.com/flake/ipetkov/crane             |
| kamadorueda/alejandra      https://flakehub.com/flake/kamadorueda/alejandra     |
| nix-community/fenix        https://flakehub.com/flake/nix-community/fenix       |
| nix-community/lanzaboote   https://flakehub.com/flake/nix-community/lanzaboote  |
| nix-community/nix-init     https://flakehub.com/flake/nix-community/nix-init    |
| nix-community/nixpkgs-fmt  https://flakehub.com/flake/nix-community/nixpkgs-fmt |
| nix-community/patsh        https://flakehub.com/flake/nix-community/patsh       |
| ryanccn/nyoom              https://flakehub.com/flake/ryanccn/nyoom             |
+---------------------------------------------------------------------------------+

Well, that query returns these results today, but this will surely change in the future as more flakes are added, included Rust-related flakes.

You can also run more complex queries, like these:

fh search "nixos modules"
fh search "flake python"

Going forward

fh is a modest tool but it brings real improvements to the experience around Nix flakes. It gives you quick access to the steadily expanding constellation of flakes on FlakeHub, including search, and to programmatically add flakes to your projects. In the near term, we have plans to support interactively creating new flake.nix files and to expand fh’s ability to modify existing flakes. So keep up to date with the fh flake for future improvements.