GitHub CLI (gh) is one of my favourite tools. In addition to its built-in commands, it allows you to write your own extensions. In this post, I will show you how to write a simple GitHub CLI extension and how to package it with Nix, in particular under Nix Home Manager.

GitHub CLI and Its Extensions

GitHub CLI (gh) is the official command-line tool for GitHub. It provides a set of commands for interacting with GitHub repositories, issues, pull requests, and more. It also provides convenience functionality to issue authenticated API requests to both REST and GraphQL APIs of GitHub:

$gh api repos/vst/hostpatrol/releases\--jq".[]|[.name,.created_at]|@csv" |    qsv tablev0.0.15  2024-04-19T07:19:14Zv0.0.14  2024-04-16T02:48:40Zv0.0.13  2024-04-15T01:46:18Z[...]

... or:

$gh api graphql-fquery='  query {    viewer {      login    }  }'{"data":{"viewer":{"login":"vst"}}}

In addition to its built-in commands,gh allows you to write aliases or your own extensions. For example, you can define an alias to list all your repositories:

$ghalias setpv'pr view'$gh pv...

Extensions are more powerful than aliases. They are written in any language and installed as a binary or a script. The extension is executed as a subcommand ofgh. You may check out theofficial gh extensions documentation for more details oravailable extensions on GitHub.

Nix Home Manager andgh

Nix Home Manager is a tool for managing a user environment with Nix. It already has a nice way to install and configuregh with theprograms.gh option:

{# ...programs.gh={enable=true;settings={aliases={co="pr checkout";pv="pr view";};};extensions=[pkgs.gh-s];};# ...}

Note theprograms.gh.extensions option. It allows you to install anygh extension from the Nixpkgs repository. However, if you want to write your own extension, you need to package it yourself. That is not a big deal!

Writing a Simple Extension

Let's say, we want to write an extension that lists all the repositories of the user. The extension is a simple shell script that uses thegh command to list the repositories current user owns and tabulates withxsv command:

#!/usr/bin/env bashgh api\  user/repos\--method GET\--raw-fieldtype=owner\--paginate\--jq'.[]|[.full_name,.url]|@csv' |  xsv table

Now, we can add it into theprograms.gh.extensions option in the Nix Home Manager configuration:

{# ...programs.gh={enable=true;settings={aliases={co="pr checkout";pv="pr view";lr="list-repos";};};extensions=[pkgs.gh-s(pkgs.writeShellApplication{name="gh-list-my-repos";derivationArgs={pname="gh-list-my-repos";};runtimeInputs=[pkgs.ghpkgs.xsv];text=''          #!/usr/bin/env bash          gh api \            user/repos \            --method GET \            --raw-field type=owner \            --paginate \            --jq '.[]|[.full_name,.url]|@csv' |            xsv table        '';})];};# ...}

Note that:

1. We used thewriteShellApplication function to create a shell script.
2. We added thegh andxsv packages as runtime inputs.
3. We added extra derivation arguments to set the package name which is needed by Nix Home Manager to install and locate the extension.

That's it! You can now use thelist-my-repos command as a subcommand ofgh:

$gh list-my-repos...