fh，FlakeHub 官方 CLI

fh 是一个用于搜索 FlakeHub 并向你的 Nix flakes 添加新 inputs 的简易 CLI。

用法

从 FlakeHub 使用 fh：

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

[!NOTE] 这会在你的计算机上本地构建 fh。预构建的二进制文件尚不可用。

安装

NixOS

要在 NixOS 系统上使 fh CLI 立即可用：

{
  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 ...
      ];
    };
  };
}

使用 fh

你可以使用 fh 来：

登录 FlakeHub
检查 FlakeHub 登录状态
初始化一个新的 flake.nix
向你的 flake.nix 添加 flake 输入
直接从 FlakeHub Cache 获取 flake 输出
将 flake 引用解析为存储路径
将 NixOS、Home Manager 和 nix-darwin 配置应用到当前系统
将 flake 输入转换为使用 FlakeHub
弹出 flake 输入
搜索 FlakeHub flakes
列出可用的 releases 和 flakes、组织及版本
按 label 列出 flakes

登录 FlakeHub

fh 是配置本地 Nix 以使用 FlakeHub 高级功能（如 FlakeHub Cache 和私有 flakes）的标准方式：

fh login

这将提示您输入一个 FlakeHub 令牌，您可以在用户设置页面的Tokens下获取。点击 New 创建新令牌，提供所需的配置，复制该令牌，将其粘贴到提示中，并按照剩余说明操作。

检查 FlakeHub 登录状态

您可以使用 fh status 命令检查您相对于 FlakeHub 的当前登录状态：

fh status

如果您当前已登录，该命令将返回如下信息：

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

从零开始初始化一个新的 `flake.nix`

fh init 会结合以下内容为您生成一个新的 flake.nix 文件：

您对交互式问题的回答
您运行该命令时所在仓库的内容。

要创建一个 flake.nix，请导航到您希望创建它的目录并运行 fh init（或使用 --root 选项指定其他目录）。响应它提供的提示，最后 fh 会将一个 flake.nix 写入磁盘。

fh init 内置支持以下语言：

[!NOTE] fh init 命令基于最佳猜测运行，并且其建议带有主观倾向。它更旨在作为一个有用的启动器，而非一个全面的 flake 创建解决方案。

将发布到 FlakeHub 的 flake 添加到您的 `flake.nix`

fh add 会将指定 flake 的最新版本添加到您的 flake.nix 中，并更新 outputs 函数以接受它。这将把 Nixpkgs 的当前版本添加到您的 flake 中：

fh add nixos/nixpkgs

生成的 flake.nix 大致如下：

{
  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
  };
}

直接获取 flake 输出

你可以使用 fh fetch 命令直接从 FlakeHub 获取 flake 输出。你需要同时指定一个 flake 引用以及 fh 应写入指向该输出 Nix 存储路径符号链接的目标链接。

示例如下：

# Fetch the output for the current system
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

fh fetch 在与 FlakeHub Cache 配合使用时最为有用，该缓存功能在 FlakeHub 的付费计划中提供。如果 flake 输出已存储在缓存中，fh fetch 可以获取缓存的输出，而无需评估同样存储在缓存中的 store 路径。

将 flake 引用解析为 store 路径

您可以使用 fh resolve 命令将 FlakeHub 上的 flake 引用解析为 Nix store 路径：

fh resolve "omnicorp/devtools/0.1.0#packages.x86_64-linux.cli"
/nix/store/1ab797rfbdcjzissxrsf25rqy0l8mksq-cli-0.1.0

您只能在 include-output-paths 设置为 true 的 flake 发布版本中使用 fh resolve。以下是一个 flakehub-push 配置示例：

- name: Publish to FlakeHub
  uses: determinatesystems/flakehub-push@main
  with:
    visibility: "public" # or "unlisted" or "private"
    include-output-paths: true

fh resolve 命令在与 FlakeHub Cache 配合使用时最为有用。如果该 flake 上启用了缓存，且当前 Nix 用户已登录到 FlakeHub，那么已解析的 store 路径也可供 Nix 使用。在这些条件下，例如，你可以应用已发布到 FlakeHub 的 NixOS 配置：

# 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

将配置应用到当前系统

fh apply 命令允许您将以下系统之一的配置应用到当前主机：

NixOS
Home Manager
nix-darwin

对于这三种系统，您只需提供配置的 flake 输出引用，fh 会完成其余工作。

NixOS

在 NixOS 系统上，您可以使用 fh apply nixos 从输出路径应用配置：

fh apply nixos "my-org/system-configs/0.1#nixosConfigurations.staging-box"

如果您未指定 flake 输出路径，fh apply nixos 将默认为 nixosConfigurations.$(hostname)。因此，以下两条命令是等效的：

fh apply nixos "my-org/system-configs/0.1#nixosConfigurations.$(hostname)"
fh apply nixos "my-org/system-configs/0.1"

fh apply nixos 首先将提供的输出引用解析为存储路径，为该路径构建 switch-to-configuration 脚本，然后默认运行 switch-to-configuration switch。您也可以从 switch 提供不同的命令（boot、test 或 dry-activate）。以下是一个示例：

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

Home Manager

如果你使用的是 Home Manager 的系统，你可以使用 fh apply home-manager 从输出路径应用配置：

fh apply home-manager "my-org/home-configs/0.1#homeConfigurations.standard-home-config"

如果您未指定 flake 输出路径，fh apply home-manager 将默认为 homeConfigurations.$(whoami)。因此，以下两条命令是等效的：

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 首先将提供的输出引用解析为存储路径，为该路径构建 activate 脚本，然后执行它。

nix-darwin

如果你使用的是基于 nix-darwin 的 macOS 系统，你可以使用 fh apply nix-darwin 从输出路径应用配置：

fh apply nix-darwin "my-org/macos-configs/0.1#darwinConfigurations.justme-aarch64-darwin"

如果您未指定 flake 输出路径，fh apply nix-darwin 将默认为 darwinConfigurations.${devicename}.system，其中 devicename 是 scutil --get LocalHostName 的输出。因此，这两个命令是等效的：

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 首先将提供的输出引用解析为存储路径，为该路径构建 darwin-rebuild 脚本，然后运行 darwin-rebuild activate。

将 flake 输入转换为使用 FlakeHub

在可能的情况下，将 flake 的 flake 输入转换为 FlakeHub 输入。

fh convert

如果你在 flake.nix 中有一个 github:NixOS/nixpkgs flake 输入，例如，该命令会自动将其转换为 https://flakehub.com/f/NixOS/nixpkgs/* 输入。

默认情况下，fh convert 会转换 flake.nix 中同一目录下的输入，但你可以通过 --flake-path 选项指定不同的路径：

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

要查看哪些输入将被转换而不将结果写入指定的 flake.nix，您可以应用 --dry-run 标志，该标志会向 stdout 打印一个列表：

fh convert --dry-run

弹出 flake 输入

在可能的情况下，将 flake 的 flake 输入从 FlakeHub 转换回 GitHub。

fh eject

如果你在 flake.nix 中有一个 https://flakehub.com/f/NixOS/nixpkgs flake 输入，例如，此命令会自动将其转换为 github:NixOS/nixpkgs 输入。

默认情况下，fh eject 会转换同一目录中 flake.nix 的输入，但你可以通过 --flake-path 选项指定不同的路径：

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

要查看哪些输入将被转换而不将结果写入指定的 flake.nix，您可以应用 --dry-run 标志，该标志会将列表打印到 stdout：

fh eject --dry-run

搜索已发布的 flakes

你可以使用 fh search 命令并传入搜索查询来搜索公开列出的 flakes。以下是一个示例：

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 支持任意搜索字符串。示例：

fh search "rust nixos"

列出发布版本

fh list releases 提供 flake 的 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    |
| ...                                                        |
+------------------------------------------------------------+

列出 flakes、组织和版本

fh list flakes、fh list orgs 和 fh list versions 分别列出了 FlakeHub 上的 flakes、organizations 和 flake versions。

列出 flakes

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

列出版本

你可以通过向 fh list versions 传递 flake 名称和版本要求来列出 flake 的 versions：

fh list versions <flake> <version_req>

这是一个示例：

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

按标签列出

您可以使用 fh list label 命令按标签列出 flakes：

fh list label <label>

这是一个示例：

fh list label python

+-------------------------------------------------------------------------------+
| Flake                     FlakeHub URL                                        |
+-------------------------------------------------------------------------------+
| nix-community/poetry2nix  https://flakehub.com/flake/nix-community/poetry2nix |
+-------------------------------------------------------------------------------+

Shell 补全

你可以使用 fh completion 命令生成 shell 补全脚本：

fh completion <shell>

这是一个示例：

fh completion bash

这些 shell 受支持：

关于自动化的说明

将 fh list 命令通过管道传递给另一个程序时，会输出 CSV 而非样式化表格。

你可以为每个列表命令应用 --json 标志以生成 JSON 输出。

许可证

Apache 2.0

支持

如需支持，请发送邮件至 support@flakehub.com 或加入我们的 Discord。

fh，FlakeHub 官方 CLI

用法

安装

NixOS

使用 fh

登录 FlakeHub

检查 FlakeHub 登录状态

从零开始初始化一个新的 flake.nix

将发布到 FlakeHub 的 flake 添加到您的 flake.nix

直接获取 flake 输出

将 flake 引用解析为 store 路径

将配置应用到当前系统

NixOS

Home Manager

nix-darwin

将 flake 输入转换为使用 FlakeHub

弹出 flake 输入

搜索已发布的 flakes

列出发布版本

列出 flakes、组织和版本

列出 flakes

列出组织

列出版本

按标签列出

Shell 补全

关于自动化的说明

许可证

支持

从零开始初始化一个新的 `flake.nix`

将发布到 FlakeHub 的 flake 添加到您的 `flake.nix`