When executing gh <cmd>, if <cmd> is not a built-in command, this searches ~/.config/gh/gh-commands/* and in PATH for executables named gh-<cmd> and runs the first one found.

All arguments are forwarded to the executable and the following environment variables are set:

• GITHUB_TOKEN for API calls;
• GH_BASEREPO (if available) with the <owner>/<repo> pair determined from git remotes.

Example: command to identify the authenticated user

#!/bin/bash
exec gh api user | jq -r .login

If saved as gh-whoami somewhere in the user's PATH, the command is invoked like so:

$ gh whoami
mislav

All custom commands are listed in shell completions for the gh command; e.g. typing gh who<Tab> will expand to gh whoami.

Additionally, the executable may provide its own shell completions by respecting when the 1st argument is __complete and writing completion options as separate lines of output:

#!/bin/bash
set -e

if [ "${1:-}" = "__complete" ]; then
  echo --some-flag
  echo --another-flag
  exit 0
fi

# ...the rest of the implementation

TODO:

• provide a command to easily install other person's command extensions with
• provide a command to update previously downloaded extensions
• handle case in which multiple commands of the same name are found under ~/.config/gh/gh-commands/*
• avoid asking for shell completions if the executable doesn't look like it implements __complete
• fix gh __complete <cmd> '' returning extra results
• write more example commands