{"id":27958403,"url":"https://github.com/determinatesystems/fh","last_synced_at":"2025-05-07T18:23:12.090Z","repository":{"id":191990769,"uuid":"683541577","full_name":"DeterminateSystems/fh","owner":"DeterminateSystems","description":"The official CLI for FlakeHub: search for flakes, and add new inputs to your Nix flake.","archived":false,"fork":false,"pushed_at":"2025-05-05T17:22:15.000Z","size":1114,"stargazers_count":136,"open_issues_count":20,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-05T17:46:42.947Z","etag":null,"topics":["cli","flake","nix","nixos"],"latest_commit_sha":null,"homepage":"https://flakehub.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeterminateSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-26T22:43:41.000Z","updated_at":"2025-05-05T17:22:18.000Z","dependencies_parsed_at":"2023-10-16T20:07:53.106Z","dependency_job_id":"6511c68d-33d3-4f27-8ad8-2ace739d6de3","html_url":"https://github.com/DeterminateSystems/fh","commit_stats":null,"previous_names":["determinatesystems/fh"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Ffh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Ffh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Ffh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Ffh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeterminateSystems","download_url":"https://codeload.github.com/DeterminateSystems/fh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252932172,"owners_count":21827240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","flake","nix","nixos"],"created_at":"2025-05-07T18:23:11.594Z","updated_at":"2025-05-07T18:23:12.069Z","avatar_url":"https://github.com/DeterminateSystems.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fh, the official FlakeHub CLI\n\n[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/DeterminateSystems/fh/badge)](https://flakehub.com/flake/DeterminateSystems/fh)\n\n**fh** is a scrappy CLI for searching [FlakeHub] and adding new [inputs] to your [Nix flakes][nix-flakes].\n\n## Usage\n\nUsing fh from FlakeHub:\n\n```shell\nnix shell \"https://flakehub.com/f/DeterminateSystems/fh/*.tar.gz\"\n```\n\n\u003e [!NOTE]\n\u003e This builds fh locally on your computer.\n\u003e Pre-built binaries aren't yet available.\n\n## Installation\n\n### NixOS\n\nTo make the fh CLI readily available on a [NixOS] system:\n\n```nix\n{\n  description = \"My NixOS config.\";\n\n  inputs.fh.url = \"https://flakehub.com/f/DeterminateSystems/fh/*.tar.gz\";\n  inputs.nixpkgs.url = \"https://flakehub.com/f/NixOS/nixpkgs/0.2305.*.tar.gz\";\n\n  outputs = { nixpkgs, fh, ... } @ inputs: {\n    nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [\n        {\n          environment.systemPackages = [ fh.packages.x86_64-linux.default ];\n        }\n\n        # ... the rest of your modules here ...\n      ];\n    };\n  };\n}\n```\n\n## Using fh\n\nYou can use fh to:\n\n- [Log into FlakeHub](#log-into-flakehub)\n- [Check FlakeHub login status](#check-flakehub-login-status)\n- [Initialize a new `flake.nix`](#initialize-a-new-flakenix-from-scratch)\n- [Add flake inputs to your `flake.nix`](#add-a-flake-published-to-flakehub-to-your-flakenix)\n- [Fetch flake outputs directly from FlakeHub Cache](#fetch-flake-outputs-directly)\n- [Resolve flake references to store paths](#resolve-flake-references-to-store-paths)\n- [Apply NixOS, Home Manager, and nix-darwin configurations to the current system](#apply-configurations-to-the-current-system)\n- [Convert flake inputs to use FlakeHub](#convert-flake-inputs-to-use-flakehub)\n- [Eject flake inputs](#eject-flake-inputs)\n- [Search FlakeHub flakes](#searching-published-flakes)\n- List available [releases](#listing-releases) and [flakes, organizations, and versions](#listing-flakes-organizations-and-versions)\n- List flakes by [label](#list-by-label)\n\n### Log into FlakeHub\n\nfh is the standard way to set up your local Nix to use [FlakeHub]'s advanced features like [FlakeHub Cache][cache] and private flakes:\n\n```shell\nfh login\n```\n\nThis will prompt you for a FlakeHub token that you can obtain under [**Tokens**][tokens] on your [user settings page][settings].\nClick **New** to create a new token, provide your desired configuration, copy the token, paste it into the prompt, and follow the remaining instructions.\n\n### Check FlakeHub login status\n\nYou can check your current login status vis-à-vis [FlakeHub] using the `fh status` command:\n\n```shell\nfh status\n```\n\nIf you are currently logged in, the command returns information like this:\n\n```\nLogged in: true\nGitHub user name: my-github-username\nToken expires at: 2025-01-22 14:41:48 -08:00\n```\n\n### Initialize a new `flake.nix` from scratch\n\n`fh init` generates a new [`flake.nix`][flakes] file for you using a combination of:\n\n1. Your responses to interactive questions\n1. The contents of the repository in which you run the command.\n\nTo 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).\nRespond to the prompts it provides you and at the end fh will write a `flake.nix` to disk.\n\n`fh init` has built-in support for the following languages:\n\n- [Elm]\n- [Go]\n- [Java]\n- [JavaScript]\n- [PHP]\n- [Python]\n- [Ruby]\n- [Rust]\n- [Zig]\n\n\u003e [!NOTE]\n\u003e The `fh init` command operates on a best-guess basis and is opinionated in its suggestions.\n\u003e It's intended less as a comprehensive flake creation solution and more as a helpful kickstarter.\n\n### Add a flake published to FlakeHub to your `flake.nix`\n\n`fh add` adds the most current release of the specified flake to your `flake.nix` and updates the `outputs` function to accept it.\nThis would add the current release of [Nixpkgs] to your flake:\n\n```shell\nfh add nixos/nixpkgs\n```\n\nThe resulting `flake.nix` would look something like this:\n\n```nix\n{\n  description = \"My new flake.\";\n\n  inputs.nixpkgs.url = \"https://flakehub.com/f/NixOS/nixpkgs/0.2305.490449.tar.gz\";\n\n  outputs = { nixpkgs, ... } @ inputs: {\n    # Fill in your outputs here\n  };\n}\n```\n\n### Fetch flake outputs directly\n\nYou can fetch [flake outputs][outputs] directly from FlakeHub using the `fh fetch` command.\nYou need to specify both a [flake reference][flakeref] and the target link to which fh should write the symlink to the output's [Nix store path][store-paths].\n\nHere's an example:\n\n```shell\n# Fetch the output for the current system\nSYSTEM=\"$(nix eval --impure --expr 'builtins.currentSystem' --raw)\"\nfh fetch \"DeterminateSystems/fh/*#packages.${SYSTEM}.default\" ./out\n\n# Run the fh executable using the target link\n./out/bin/fh --help\n```\n\n`fh fetch` is most useful when used in conjunction with [FlakeHub Cache][cache], which is available on FlakeHub [paid plans][signup].\nIf 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][resolved-store-paths] in the cache.\n\n### Resolve flake references to store paths\n\nYou can resolve flake references on FlakeHub to Nix store paths using the `fh resolve` command:\n\n```shell\nfh resolve \"omnicorp/devtools/0.1.0#packages.x86_64-linux.cli\"\n/nix/store/1ab797rfbdcjzissxrsf25rqy0l8mksq-cli-0.1.0\n```\n\nYou can only use `fh resolve` with flake releases for which [`include-output-paths`][flakehub-push-params] has been set to `true`.\nHere's an example [flakehub-push] configuration:\n\n```yaml\n- name: Publish to FlakeHub\n  uses: determinatesystems/flakehub-push@main\n  with:\n    visibility: \"public\" # or \"unlisted\" or \"private\"\n    include-output-paths: true\n```\n\nThe `fh resolve` command is most useful when used in conjunction with [FlakeHub Cache][cache].\nIf the cache is enabled on the flake and the current Nix user is [logged into FlakeHub](#log-into-flakehub), then resolved store paths are also available to Nix.\nUnder those conditions, you can, for example, apply a NixOS configuration published to FlakeHub:\n\n```shell\n# Build the derivation\nnix build \\\n  --max-jobs 0 \\\n  --profile /nix/var/nix/profiles/system \\\n  $(fh resolve \"my-org/my-nixos-configs#nixosConfigurations.my-dev-workstation\")\n\n# Apply the configuration\n/nix/var/nix/profiles/system/bin/switch-to-configuration switch\n```\n\n### Apply configurations to the current system\n\nThe `fh apply` command enables you to apply a configuration for one of the following systems to the current host:\n\n- [NixOS](#nixos)\n- [Home Manager](#home-manager)\n- [nix-darwin](#nix-darwin)\n\nFor all three systems, you only need to supply a flake output reference for the configuration and fh does the rest.\n\n#### NixOS\n\nOn a [NixOS] system, you can use `fh apply nixos` to apply a configuration from an output path:\n\n```shell\nfh apply nixos \"my-org/system-configs/0.1#nixosConfigurations.staging-box\"\n```\n\nIf you don't specify a flake output path, `fh apply nixos` defaults to `nixosConfigurations.$(hostname)`.\nThese two commands are thus equivalent:\n\n```shell\nfh apply nixos \"my-org/system-configs/0.1#nixosConfigurations.$(hostname)\"\nfh apply nixos \"my-org/system-configs/0.1\"\n```\n\n`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.\nYou can also supply a different command from `switch` (`boot`, `test`, or `dry-activate`).\nHere's an example:\n\n```shell\nfh apply nixos \"my-org/system-configs/0.1\" boot\n```\n\n#### Home Manager\n\nIf you're on a system that uses [Home Manager][hm], you can use `fh apply home-manager` to apply a configuration from an output path:\n\n```shell\nfh apply home-manager \"my-org/home-configs/0.1#homeConfigurations.standard-home-config\"\n```\n\nIf you don't specify a flake output path, `fh apply home-manager` defaults to `homeConfigurations.$(whoami)`.\nThese two commands are thus equivalent:\n\n```shell\nfh apply home-manager \"my-org/home-configs/0.1#homeConfigurations.$(whoami)\"\nfh apply home-manager \"my-org/home-configs/0.1\"\n```\n\n`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.\n\n#### nix-darwin\n\nIf 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:\n\n```shell\nfh apply nix-darwin \"my-org/macos-configs/0.1#darwinConfigurations.justme-aarch64-darwin\"\n```\n\nIf 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`.\nThese two commands are thus equivalent:\n\n```shell\nfh apply nix-darwin \"my-org/macos-configs/0.1#darwinConfigurations.$(scutil --get LocalHostName)\"\nfh apply nix-darwin \"my-org/macos-configs/0.1\"\n```\n\n`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`.\n\n### Convert flake inputs to use FlakeHub\n\nConvert a [flake][flakes]'s flake inputs into [FlakeHub] inputs when possible.\n\n```shell\nfh convert\n```\n\nIf 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.\n\nBy 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:\n\n```shell\nfh convert --flake-path /my-project/flake.nix\n```\n\nTo 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:\n\n```shell\nfh convert --dry-run\n```\n\n### Eject flake inputs\n\nConvert a [flake][flakes]'s flake inputs from [FlakeHub] back to GitHub when possible.\n\n```shell\nfh eject\n```\n\nIf 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.\n\nBy 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:\n\n```shell\nfh eject --flake-path /my-project/flake.nix\n```\n\nTo 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:\n\n```shell\nfh eject --dry-run\n```\n\n### Searching published flakes\n\nYou can search publicly listed flakes using the `fh search` command and passing in a search query.\nHere's an example:\n\n```shell\nfh search rust\n```\n\n```console\n+---------------------------------------------------------------------------------+\n| Flake                      FlakeHub URL                                         |\n+---------------------------------------------------------------------------------+\n| astro/deadnix              https://flakehub.com/flake/astro/deadnix             |\n| carlthome/ml-runtimes      https://flakehub.com/flake/carlthome/ml-runtimes     |\n| ipetkov/crane              https://flakehub.com/flake/ipetkov/crane             |\n| kamadorueda/alejandra      https://flakehub.com/flake/kamadorueda/alejandra     |\n| nix-community/fenix        https://flakehub.com/flake/nix-community/fenix       |\n| nix-community/lanzaboote   https://flakehub.com/flake/nix-community/lanzaboote  |\n| nix-community/nix-init     https://flakehub.com/flake/nix-community/nix-init    |\n| nix-community/nixpkgs-fmt  https://flakehub.com/flake/nix-community/nixpkgs-fmt |\n| nix-community/patsh        https://flakehub.com/flake/nix-community/patsh       |\n| ryanccn/nyoom              https://flakehub.com/flake/ryanccn/nyoom             |\n+---------------------------------------------------------------------------------+\n```\n\n`fh search` supports arbitrary search strings.\nAn example:\n\n```shell\nfh search \"rust nixos\"\n```\n\n### Listing releases\n\n`fh list releases` provides a list of a flake's [releases][semver].\n\n```shell\nfh list releases nixos/nixpkgs\n```\n\n```console\n+------------------------------------------------------------+\n| Version                                                    |\n+------------------------------------------------------------+\n| 0.1.428801+rev-2788904d26dda6cfa1921c5abb7a2466ffe3cb8c    |\n| 0.1.429057+rev-42337aad353c5efff4382d7bf99deda491459845    |\n| 0.1.429304+rev-27ccd29078f974ddbdd7edc8e38c8c8ae003c877    |\n| 0.1.429553+rev-5dc7114b7b256d217fe7752f1614be2514e61bb8    |\n| 0.1.429868+rev-a115bb9bd56831941be3776c8a94005867f316a7    |\n| ...                                                        |\n+------------------------------------------------------------+\n```\n\n### Listing flakes, organizations, and versions\n\n[`fh list flakes`](#list-flakes), [`fh list orgs`](#list-flakes), and [`fh list versions`](#list-versions) enumerate [flakes], [organizations][orgs], and [flake versions][semver] on FlakeHub, respectively.\n\n#### List flakes\n\n```shell\nfh list flakes\n```\n\n```console\n+---------------------------------------------------------------------------------------------------------------+\n| Flake                                     FlakeHub URL                                                        |\n+---------------------------------------------------------------------------------------------------------------+\n| ajaxbits/audiobookshelf                   https://flakehub.com/flake/ajaxbits/audiobookshelf                  |\n| ajaxbits/tone                             https://flakehub.com/flake/ajaxbits/tone                            |\n| astro/deadnix                             https://flakehub.com/flake/astro/deadnix                            |\n| ...                                       ...                                                                 |\n+---------------------------------------------------------------------------------------------------------------+\n```\n\n#### List orgs\n\n```shell\nfh list orgs\n```\n\n```console\n+-------------------------------------------------------------------------+\n| Organization            FlakeHub URL                                    |\n+-------------------------------------------------------------------------+\n| ajaxbits                https://flakehub.com/org/ajaxbits               |\n| astro                   https://flakehub.com/org/astro                  |\n| ...                     ...                                             |\n+-------------------------------------------------------------------------+\n```\n\n#### List versions\n\nYour can list [versions][semver] of a flake by passing the flake name and a version requirement to `fh list versions`:\n\n```shell\nfh list versions \u003cflake\u003e \u003cversion_req\u003e\n```\n\nHere's an example:\n\n```shell\nfh list versions DeterminateSystems/flake-checker \"0.1.*\"\n```\n\n```console\n+------------------------------------------------------------------------------------------------------+\n| Simplified version  FlakeHub URL                                                        Full version |\n+------------------------------------------------------------------------------------------------------+\n| 0.1.0               https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.0   0.1.0        |\n| 0.1.1               https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.1   0.1.1        |\n| 0.1.2               https://flakehub.com/flake/DeterminateSystems/flake-checker/0.1.2   0.1.2        |\n| ...                 ...                                                                 ...          |\n+------------------------------------------------------------------------------------------------------+\n```\n\n### List by label\n\nYou can list flakes by label using the `fh list label` comand:\n\n```shell\nfh list label \u003clabel\u003e\n```\n\nHere's an example:\n\n```shell\nfh list label python\n```\n\n```console\n+-------------------------------------------------------------------------------+\n| Flake                     FlakeHub URL                                        |\n+-------------------------------------------------------------------------------+\n| nix-community/poetry2nix  https://flakehub.com/flake/nix-community/poetry2nix |\n+-------------------------------------------------------------------------------+\n```\n\n## Shell completion\n\nYou can generate shell completion scripts using the `fh completion` command:\n\n```shell\nfh completion \u003cshell\u003e\n```\n\nHere's an example:\n\n```shell\nfh completion bash\n```\n\nThese shells are supported:\n\n- [Bash]\n- [Elvish]\n- [Fish]\n- [Powershell]\n- [zsh]\n\n## A note on automation\n\nPiping `fh list` commands to another program emits [CSV] instead of the stylized table.\n\nYou can apply the `--json` flag to each list command to produce JSON output.\n\n## License\n\n[Apache 2.0](https://choosealicense.com/licenses/apache-2.0/)\n\n## Support\n\nFor support, email support@flakehub.com or [join our Discord](https://discord.gg/invite/a4EcQQ8STr).\n\n[bash]: https://gnu.org/software/bash\n[cache]: https://flakehub.com/cache\n[csv]: https://en.wikipedia.org/wiki/Comma-separated_values\n[elm]: https://elm-lang.org\n[elvish]: https://elv.sh\n[fish]: https://fishshell.com\n[flakehub]: https://flakehub.com\n[flakehub-push]: https://github.com/determinateSystems/flakehub-push\n[flakehub-push-params]: https://github.com/determinateSystems/flakehub-push?tab=readme-ov-file#available-parameters\n[flakeref]: https://zero-to-nix.com/concepts/flakes#references\n[flakes]: https://flakehub.com/flakes\n[go]: https://golang.org\n[hm]: https://github.com/nix-community/home-manager\n[inputs]: https://zero-to-nix.com/concepts/flakes#inputs\n[java]: https://java.com\n[javascript]: https://javascript.info\n[nix-darwin]: https://github.com/LnL7/nix-darwin\n[nix-flakes]: https://zero-to-nix.com/concepts/flakes\n[nixos]: https://zero-to-nix.com/concepts/nixos\n[nixpkgs]: https://zero-to-nix.com/concepts/nixpkgs\n[orgs]: https://flakehub.com/orgs\n[outputs]: https://zero-to-nix.com/concepts/flakes#outputs\n[php]: https://php.net\n[powershell]: https://learn.microsoft.com/powershell\n[python]: https://python.org\n[resolved-store-paths]: https://docs.determinate.systems/flakehub/store-paths\n[ruby]: https://ruby-lang.org\n[rust]: https://rust-lang.org\n[semver]: https://flakehub.com/docs/concepts/semver\n[settings]: https://flakehub.com/user/settings\n[signup]: https://flakehub.com/signup\n[store-paths]: https://zero-to-nix.com/concepts/nix-store#store-paths\n[tokens]: https://flakehub.com/user/settings?editview=tokens\n[zig]: https://ziglang.org\n[zsh]: https://zsh.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeterminatesystems%2Ffh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeterminatesystems%2Ffh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeterminatesystems%2Ffh/lists"}