fh
is a scrappy CLI for searching FlakeHub and adding new inputs to your Nix flakes.
Using fh
from FlakeHub:
nix shell "https://flakehub.com/f/DeterminateSystems/fh/*.tar.gz"
Note
This builds fh
locally on your computer.
Pre-built binaries aren't yet available.
To make the fh
CLI readily available on a NixOS system:
{
description = "My NixOS config.";
inputs.fh.url = "https://flakehub.com/f/DeterminateSystems/fh/*.tar.gz";
inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2305.*.tar.gz";
outputs = { nixpkgs, fh, ... } @ inputs: {
nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{
environment.systemPackages = [ fh.packages.x86_64-linux.default ];
}
# ... the rest of your modules here ...
];
};
};
}
You can use fh
to:
- Log into FlakeHub
- Initialize a new
flake.nix
- Add flake inputs to your
flake.nix
- Resolve flake references to store paths
- Search FlakeHub flakes
- List available releases and flakes, organizations, and versions
- List flakes by label
fh
is the standard way to set up your local Nix to use FlakeHub's advanced features like FlakeHub Cache and private flakes:
fh login
This will prompt you for a FlakeHub token that you can obtain under Tokens on your user settings page. Click New to create a new token, provide your desired configuration, copy the token, paste it into the prompt, and follow the remaining instructions.
fh init
generates a new flake.nix
file for you using a combination of:
- Your responses to interactive questions
- The contents of the repository in which you run the command.
To create a flake.nix
, navigate to the directory where you want to create it and run fh init
(or specify a different directory using the --root
option).
Respond to the prompts it provides you and at the end fh
will write a flake.nix
to disk.
fh init
has built-in support for the following languages:
Note
The fh init
command operates on a best-guess basis and is opinionated in its suggestions.
It's intended less as a comprehensive flake creation solution and more as a helpful kickstarter.
fh add
adds the most current release of the specified flake to your flake.nix
and updates the outputs
function to accept it.
This would add the current release of Nixpkgs to your flake:
fh add nixos/nixpkgs
The resulting flake.nix
would look something like this:
{
description = "My new flake.";
inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2305.490449.tar.gz";
outputs = { nixpkgs, ... } @ inputs: {
# Fill in your outputs here
};
}
You can resolve flake references on FlakeHub to Nix store paths using the fh resolve
command:
fh resolve "omnicorp/devtools/0.1.0#packages.x86_64-linux.cli"
/nix/store/1ab797rfbdcjzissxrsf25rqy0l8mksq-cli-0.1.0
You can only use fh resolve
with flake releases for which include-output-paths
has been set to true
.
Here's an example flakehub-push configuration:
- name: Publish to FlakeHub
uses: determinatesystems/flakehub-push@main
with:
visibility: "public" # or "unlisted" or "private"
include-output-paths: true
The fh resolve
command is most useful when used in conjunction with FlakeHub Cache.
If the cache is enabled on the flake and the current Nix user is logged into FlakeHub, then resolved store paths are also available to Nix.
Under those conditions, you can, for example, apply a NixOS configuration published to FlakeHub:
# Build the derivation
nix build \
--max-jobs 0 \
--profile /nix/var/nix/profiles/system \
$(fh resolve "my-org/my-nixos-configs#nixosConfigurations.my-dev-workstation")
# Apply the configuration
/nix/var/nix/profiles/system/bin/switch-to-configuration switch
The fh apply
command enables you to apply a configuration for one of the following systems to the current host:
For all three systems, you only need to supply a flake output reference for the configuration and fh
does the rest.
On a NixOS system, you can use fh apply nixos
to apply a configuration from an output path:
fh apply nixos "my-org/system-configs/0.1#nixosConfigurations.staging-box"
If you don't specify a flake output path, fh apply nixos
defaults to nixosConfigurations.$(hostname)
.
These two commands are thus equivalent:
fh apply nixos "my-org/system-configs/0.1#nixosConfigurations.$(hostname)"
fh apply nixos "my-org/system-configs/0.1"
fh apply nixos
first resolves the supplied output reference to a store path, builds the switch-to-configuration
script for that path, and then runs switch-to-configuration switch
by default.
You can also supply a different command from switch
(boot
, test
, or dry-activate
).
Here's an example:
fh apply nixos "my-org/system-configs/0.1" boot
If you're on a system that uses Home Manager, you can use fh apply home-manager
to apply a configuration from an output path:
fh apply home-manager "my-org/home-configs/0.1#homeConfigurations.standard-home-config"
If you don't specify a flake output path, fh apply home-manager
defaults to homeConfigurations.$(whoami)
.
These two commands are thus equivalent:
fh apply home-manager "my-org/home-configs/0.1#homeConfigurations.$(whoami)"
fh apply home-manager "my-org/home-configs/0.1"
fh apply home-manager
first resolves the supplied output reference to a store path, builds the activate
script for that path, and then runs it.
If you're on a macOS system that uses nix-darwin, you can use fh apply nix-darwin
to apply a configuration from an output path:
fh apply nix-darwin "my-org/macos-configs/0.1#darwinConfigurations.justme-aarch64-darwin"
If you don't specify a flake output path, fh apply nix-darwin
defaults to darwinConfigurations.${devicename}.system
, where devicename
is the output of scutil --get LocalHostName
.
These two commands are thus equivalent:
fh apply nix-darwin "my-org/macos-configs/0.1#darwinConfigurations.$(scutil --get LocalHostName)"
fh apply nix-darwin "my-org/macos-configs/0.1"
fh apply nix-darwin
first resolves the supplied output reference to a store path, builds the darwin-rebuild
script for that path, and then runs darwin-rebuild activate
.
You can search publicly listed flakes using the fh search
command and passing in a search query.
Here's an example:
fh search rust
+---------------------------------------------------------------------------------+
| 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 |
+---------------------------------------------------------------------------------+
fh search
supports arbitrary search strings.
An example:
fh search "rust nixos"
fh list releases
provides a list of a flake's releases.
fh list releases nixos/nixpkgs
+------------------------------------------------------------+
| Version |
+------------------------------------------------------------+
| 0.1.428801+rev-2788904d26dda6cfa1921c5abb7a2466ffe3cb8c |
| 0.1.429057+rev-42337aad353c5efff4382d7bf99deda491459845 |
| 0.1.429304+rev-27ccd29078f974ddbdd7edc8e38c8c8ae003c877 |
| 0.1.429553+rev-5dc7114b7b256d217fe7752f1614be2514e61bb8 |
| 0.1.429868+rev-a115bb9bd56831941be3776c8a94005867f316a7 |
| ... |
+------------------------------------------------------------+
fh list flakes
, fh list orgs
, and fh list versions
enumerate flakes, organizations, and flake versions on FlakeHub, respectively.
fh list flakes
+---------------------------------------------------------------------------------------------------------------+
| Flake FlakeHub URL |
+---------------------------------------------------------------------------------------------------------------+
| ajaxbits/audiobookshelf https://flakehub.com/flake/ajaxbits/audiobookshelf |
| ajaxbits/tone https://flakehub.com/flake/ajaxbits/tone |
| astro/deadnix https://flakehub.com/flake/astro/deadnix |
| ... ... |
+---------------------------------------------------------------------------------------------------------------+
fh list orgs
+-------------------------------------------------------------------------+
| Organization FlakeHub URL |
+-------------------------------------------------------------------------+
| ajaxbits https://flakehub.com/org/ajaxbits |
| astro https://flakehub.com/org/astro |
| ... ... |
+-------------------------------------------------------------------------+
Your can list versions of a flake by passing the flake name and a version requirement to fh list versions
:
fh list versions <flake> <version_req>
Here's an example:
fh list versions DeterminateSystems/flake-checker "0.1.*"
+------------------------------------------------------------------------------------------------------+
| Simplified version FlakeHub URL Full version |
+------------------------------------------------------------------------------------------------------+
| 0.1.0 https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.0 0.1.0 |
| 0.1.1 https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.1 0.1.1 |
| 0.1.2 https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.2 0.1.2 |
| ... ... ... |
+------------------------------------------------------------------------------------------------------+
You can list flakes by label using the fh list label
comand:
fh list label <label>
Here's an example:
fh list label python
+-------------------------------------------------------------------------------+
| Flake FlakeHub URL |
+-------------------------------------------------------------------------------+
| nix-community/poetry2nix https://flakehub.com/flake/nix-community/poetry2nix |
+-------------------------------------------------------------------------------+
You can generate shell completion scripts using the fh completion
command:
fh completion <shell>
Here's an example:
fh completion bash
These shells are supported:
Piping fh list
commands to another program emits CSV instead of the stylized table.
You can apply the --json
flag to each list command to produce JSON output.
For support, email [email protected] or join our Discord.