GitHub CLI Extension Creator

Create custom GitHub CLI commands by building extensions that anyone can install and use. Extensions can be simple bash scripts or precompiled binaries in Go or other languages.

What This Skill Does

This skill helps you create GitHub CLI extensions following GitHub's official conventions. Extensions are custom commands that extend `gh` functionality, distributed as repositories with names starting with `gh-`.

Instructions

1. Determine Extension Type

Ask the user what type of extension they want to create:

2. Create Extension Using `gh extension create`

**For interpreted extensions:**

```bash

gh extension create EXTENSION-NAME

```

**For Go precompiled extensions:**

```bash

gh extension create --precompiled=go EXTENSION-NAME

```

**For other precompiled extensions:**

```bash

gh extension create --precompiled=other EXTENSION-NAME

```

Follow the interactive wizard if no arguments are provided to `gh extension create`.

3. Manual Creation (If Needed)

**For interpreted extensions:**

1. Create directory: `gh-EXTENSION-NAME`

2. Add executable file with same name as directory

3. Make file executable:

- Unix: `chmod +x file_name`

- Windows: `git init -b main && git add file_name && git update-index --chmod=+x file_name`

4. Write script using bash or another interpreter

5. Install locally: `gh extension install .`

6. Test: `gh EXTENSION-NAME`

7. Create repository:

```bash

git init -b main

git add . && git commit -m "initial commit"

gh repo create gh-EXTENSION-NAME --source=. --public --push

```

**For Go precompiled extensions:**

1. Create directory: `gh-EXTENSION-NAME`

2. Add Go source code

3. Install locally: `gh extension install .`

4. Initialize Go module: `go mod init github.com/YOUR-USERNAME/gh-EXTENSION-NAME`

5. Build: `go mod tidy && go build`

6. Test: `gh EXTENSION-NAME`

7. Create repository (exclude binary):

```bash

git init -b main

echo "gh-EXTENSION-NAME" >> .gitignore

git add main.go go.* .gitignore && git commit -m 'Initial commit'

gh repo create "gh-EXTENSION-NAME"

```

8. Create release with cross-compiled binaries:

```bash

git tag v1.0.0

git push origin v1.0.0

GOOS=windows GOARCH=amd64 go build -o gh-EXTENSION-NAME-windows-amd64.exe

GOOS=linux GOARCH=amd64 go build -o gh-EXTENSION-NAME-linux-amd64

GOOS=darwin GOARCH=amd64 go build -o gh-EXTENSION-NAME-darwin-amd64

gh release create v1.0.0 ./*amd64*

```

4. Best Practices for Interpreted Extensions

**Handling arguments and flags:**

```bash

#!/usr/bin/env bash

set -e

verbose=""

name_arg=""

while [ $# -gt 0 ]; do

case "$1" in

--verbose)

verbose=1

;;

--name)

name_arg="$2"

shift

;;

-h|--help)

echo "Add help text here."

exit 0

;;

esac

shift

done

```

**Calling core commands non-interactively:**

```bash

gh issue create --title "My Title" --body "Issue description"

```

**Fetching data programmatically:**

```bash

Get JSON data

gh pr list --json number,title,mergeStateStatus

Use GitHub API directly

gh api user

Filter with jq

gh api user --jq '.name'

```

5. Best Practices for Precompiled Extensions

**Use go-gh library for Go extensions:**

```go

package main

import (

"github.com/cli/go-gh"

"fmt"

)

func main() {

args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"`}

stdOut, _, err := gh.Exec(args...)

if err != nil {

fmt.Println(err)

return

}

fmt.Println(stdOut.String())

}

```

**Automate releases:**

6. Publishing and Discovery

After creating the repository, add the `gh-extension` topic to help users discover your extension:

1. Go to repository settings

2. Add topic: `gh-extension`

3. Extension will appear on the [gh-extension topic page](https://github.com/topics/gh-extension)

7. Testing the Extension

Install and test your extension:

```bash

Install from local directory

gh extension install .

Install from GitHub

gh extension install YOUR-USERNAME/gh-EXTENSION-NAME

Run extension

gh EXTENSION-NAME [args]

```

Examples

**Simple whoami extension:**

```bash

#!/usr/bin/env bash

set -e

exec gh api user --jq '"You are @\(.login) (\(.name))."'

```

**Go-based extension:**

```go

package main

import (

"github.com/cli/go-gh"

"fmt"

)

func main() {

args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"`}

stdOut, _, err := gh.Exec(args...)

if err != nil {

fmt.Println(err)

return

}

fmt.Println(stdOut.String())

}

```

Important Notes

References