Image for post flakehub-cli
Sep 1, 2023 by Luc Perkins

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:

Terminal window
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:

Terminal window
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:

Terminal window
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 enables you to search FlakeHub’s Algolia index of flakes using an arbitrary string query. Here’s an example:

Terminal window
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:

Terminal window
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.


Share
Avatar for Luc Perkins
Written by Luc Perkins

Luc is a technical writer, software engineer, and Nix advocate who's always on the lookout for qualitatively better ways of building software. He originally hails from the Pacific Northwest but has recently taken to living abroad.