fh: the FlakeHub CLI

FlakeHub has a dedicated CLI called fh that you can use to perform a variety of actions against the platform, such as logging in to FlakeHub, applying configurations for NixOS, Home Manager, and nix-darwin published on FlakeHub to the current system, initializing new Nix flakes, and more. To add the CLI to your current shell environment:

Add fh to your current shell environment

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

Installation

The nix shell command above builds fh locally on your computer. We will provide pre-built binaries soon.

NixOS

To make the fh CLI available on a NixOS system:

flake.nix

{
  description = "My NixOS config";
 
  inputs.fh.url = "https://flakehub.com/f/DeterminateSystems/fh/*";
  inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2405.*";
 
  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 ...
      ];
    };
  };
}

Commands

fh enables you to do a perform a variety of actions against FlakeHub:

Command	What it does	Example
`fh add`	Adds a flake input to a `flake.nix` file	`fh add ublue-os/fleek`
`fh apply`	Apply a NixOS, Home Manager, or nix-darwin configuration to the current host from a closure cached in FlakeHub Cache
`fh completion`	Provides auto-completion scripts for a variety of common shells	`fh completion bash`
`fh convert`	Convert a flake’s flake inputs to FlakeHub inputs when possible	`fh convert`
`fh eject`	Convert flake inputs from FlakeHub back to GitHub	`fh eject`
`fh init`	Creates a new `flake.nix` file for you using a combination of the contents of your project and your user input	`fh init`
`fh login`	Log in to FlakeHub
`fh list flakes`	Lists all public flakes on FlakeHub	`fh list flakes`
`fh list orgs`	Lists all public organizations on FlakeHub	`fh list orgs`
`fh list releases`	Lists all public releases for a flake	`fh list releases DeterminateSystems/nuenv`
`fh list versions`	Lists all public releases for a flake that match the provided version requirement	`fh list versions NixOS/nixpkgs "0.2305.*"`
`fh fetch`	Fetch flake outputs directly from FlakeHub Cache
`fh resolve`	Fetches a resolved store path for a flake reference	`fh resolve my-org/my-flake/*#nixosConfigurations.prod-server`
`fh search`	Lists all flakes that match the provided search query	`fh search "home manager"`
`fh status`	Check your current FlakeHub login status	`fh status`

Add

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:

Add a Nixpkgs input to the current flake

fh add nixos/nixpkgs

The resulting flake.nix would look something like this:

flake.nix

{
  description = "My new flake.";
 
  inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2305.490449";
 
  outputs = { nixpkgs, ... } @ inputs: {
    # Fill in your outputs here
  };
}

Apply configuration

The fh apply command is used to apply store paths already stored in FlakeHub Cache, which requires you to sign up for a paid plan on FlakeHub.

fh has an apply command that you can use to apply a configuration for one of these systems to the current host:

https://flakehub.com/f/:org/:project/:version-req#:output

staticrequired

For all three systems, you can also omit the flake output and use a URL of this form:

https://flakehub.com/f/:org/:project/:version-req

staticrequired

How fh infers the output differs on each system, as explained in the sections below.

NixOS

On a NixOS system, you can use fh apply nixos to apply a configuration from an output path:

Apply a NixOS configuration

sudo 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:

Equivalent fh apply nixos commands

sudo fh apply nixos "my-org/system-configs/0.1#nixosConfigurations.$(hostname)"
sudo 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:

Non-switch command

fh apply nixos "my-org/system-configs/0.1" boot

Home Manager

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:

Apply a Home Manager configuration

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:

Equivalent fh apply home-manager commands

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.

nix-darwin

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:

Apply a nix-darwin configuration

sudo 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:

Equivalent fh apply nix-darwin commands

sudo fh apply nix-darwin "my-org/macos-configs/0.1#darwinConfigurations.$(scutil --get LocalHostName)"
sudo 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.

Shell completion

You can generate shell completion scripts using the fh completion command:

Output the shell completion script for the specified shell

fh completion <shell>

Here’s an example:

Output the shell completion script for Bash

fh completion bash

These shells are supported:

Convert flake inputs to FlakeHub

Convert a flake’s flake inputs into FlakeHub inputs when possible.

Convert the current flake's inputs to FlakeHub inputs

fh convert

If you had a github:NixOS/nixpkgs flake input in a flake.nix, for example, this command would automatically convert it into a https://flakehub.com/f/NixOS/nixpkgs input.

By default, fh convert converts the inputs in the flake.nix in the same directory but you can specify a different path using the --flake-path option:

Convert the specified flake's inputs to FlakeHub inputs

fh convert --flake-path /my-project/flake.nix

To see which inputs would be converted without writing the results to the specified flake.nix, you can apply the --dry-run flag, which prints a list to stdout:

Perform a conversion dry run

fh convert --dry-run

Eject flake inputs

Convert a flake’s flake inputs from FlakeHub back to GitHub when possible.

Convert the current flake's inputs from FlakeHub to GitHub

fh eject

If you had a https://flakehub.com/f/NixOS/nixpkgs flake input in a flake.nix, for example, this command would automatically convert it into a github:NixOS/nixpkgs input.

By default, fh eject converts the inputs in the flake.nix in the same directory but you can specify a different path using the --flake-path option:

Convert the specified flake's inputs from FlakeHub to GitHub

fh eject --flake-path /my-project/flake.nix

To see which inputs would be converted without writing the results to the specified flake.nix, you can apply the --dry-run flag, which prints a list to stdout:

Perform an ejection dry run

fh eject --dry-run

Initialize flakes from scratch

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 these languages:

⚠️

fh init 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.

List

fh enables you to list a variety of FlakeHub resources.

List flakes

List all public flakes

fh list flakes

The output would look like this:

Table output for flake list

+---------------------------------------------------------------------------------------------------------------+
| Flake                                     FlakeHub URL                                                        |
├---------------------------------------------------------------------------------------------------------------┤
| 0utkarsh/nixconfig                        https://flakehub.com/flake/0utkarsh/nixconfig                       |
| 0x5a4/nand2tetris-flake                   https://flakehub.com/flake/0x5a4/nand2tetris-flake                  |
| 0x61nas/lqth                              https://flakehub.com/flake/0x61nas/lqth                             |
| ...                                       ...                                                                 |
+---------------------------------------------------------------------------------------------------------------+

List organizations

List all public organizations

fh list orgs

The output would look like this:

Table output for organization list

+-------------------------------------------------------------------------+
| Organization            FlakeHub URL                                    |
├-------------------------------------------------------------------------┤
| Above-Os                https://flakehub.com/org/Above-Os               |
| atomic-studio-org       https://flakehub.com/org/atomic-studio-org      |
| blue-build              https://flakehub.com/org/blue-build             |
| ...                     ...                                             |
+-------------------------------------------------------------------------+

List releases

fh list releases provides a list of a flake’s releases.

List all releases for a flake

fh list releases nixos/nixpkgs

The output would look something like this:

Table output for release list

+------------------------------------------------------------+
| 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    |
| ...                                                        |
+------------------------------------------------------------+

List versions

Your can list versions of a flake by passing the flake name and a version requirement to fh list versions:

List all flake releases matching the supplied version constraint

fh list versions <flake> <version_req>

Here’s an example:

List all flake-checker releases for the supplied constraint

fh list versions DeterminateSystems/flake-checker "0.1.*"

The output would look something like this:

Table output for flake release list

+------------------------------------------------------------------------------------------------------+
| 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        |
| ...                 ...                                                                 ...          |
+------------------------------------------------------------------------------------------------------+

List by label

You can list flakes by label using the fh list label command:

List all flakes with the specified label

fh list label <label>

Here’s an example:

List all flakes with the label 'python'

fh list label python

The output would look something like this:

Table output for flake list

+-------------------------------------------------------------------------------+
| Flake                     FlakeHub URL                                        |
├-------------------------------------------------------------------------------┤
| copier-org/copier         https://flakehub.com/flake/copier-org/copier        |
| nix-community/nix-init    https://flakehub.com/flake/nix-community/nix-init   |
| nix-community/poetry2nix  https://flakehub.com/flake/nix-community/poetry2nix |
+-------------------------------------------------------------------------------

Fetch flake outputs directly from FlakeHub Cache

You can fetch flake outputs directly from FlakeHub Cache using the fh fetch command. You need to specify both a flake reference and the target link to which fh should write the symlink to the output’s Nix store path.

Here’s an example:

Fetch flake output using fh

# Fetch an output for the current system from FlakeHub Cache
SYSTEM="$(nix eval --impure --expr 'builtins.currentSystem' --raw)"
fh fetch "DeterminateSystems/fh/*#packages.${SYSTEM}.default" ./out
 
# Run the fh executable using the target link
./out/bin/fh --help

If the flake output is stored in the cache, fh fetch can fetch the cached output without needing to evaluate the store path, which is also stored in the cache.

When you fetch a flake output using fh fetch, you fetch the output’s entire closure and store it in the Nix store. it doesn’t perform any kind of bundling into a single artifact à la nix bundle. If you’d be interested in a capability like that, reach out to support@determinate.systems.

Resolve store paths

You can resolve flake references on FlakeHub to Nix store paths using the fh resolve command. Here’s an example:

Fetch a resolved store path

fh resolve "omnicorp/devtools/0.1.0#packages.x86_64-linux.cli"

And an example fetched store path:

/nix/store/
1ab797rfbdcjzissxrsf25rqy0l8mksq
-cli-0.1.0

You can only use fh resolve with flake releases for which include-store-paths has been set to true. Here’s an example flakehub-push configuration:

.github/workflows/publish-to-flakehub.yaml

- name: Publish to FlakeHub
  uses: determinatesystems/flakehub-push@main
  with:
    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:

Applying a NixOS configuration the hard way

# 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

Alternatively, you can use fh apply.

Search

You can search publicly listed flakes using the fh search command and passing in a search query. Here’s an example:

Search flakes using a keyword

fh search rust

The output would look like this:

Table output for search results

+---------------------------------------------------------------------------------+
| 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:

Search flakes using an arbitrary search string

fh search "rust nixos"

Check FlakeHub login status

You can check your current login status vis-à-vis FlakeHub using the fh status command:

Display FlakeHub authentication status

fh status

If you are currently logged in, the command returns information like this:

Logged in: true
GitHub user name: my-github-username
Token expires at: 2025-01-22 14:41:48 -08:00

Resolved store paths Flake discovery

fh: the FlakeHub CLI

Installation

NixOS

Commands

Add

Apply configuration

NixOS

Home Manager

nix-darwin

Shell completion

Convert flake inputs to FlakeHub

Eject flake inputs

Initialize flakes from scratch

List

List flakes

List organizations

List releases

List versions

List by label

Login

Fetch flake outputs directly from FlakeHub Cache

Resolve store paths

Search

Check FlakeHub login status