1# Go library for the GitHub CLI
2
3`go-gh` is a collection of Go modules to make authoring [GitHub CLI extensions][extensions] easier.
4
5Modules from this library will obey GitHub CLI conventions by default:
6
7- [`repository.Current()`](https://pkg.go.dev/github.com/cli/go-gh/v2/pkg/repository#current) respects the value of the `GH_REPO` environment variable and reads from git remote configuration as fallback.
8
9- GitHub API requests will be authenticated using the same mechanism as `gh`, i.e. using the values of `GH_TOKEN` and `GH_HOST` environment variables and falling back to the user's stored OAuth token.
10
11- [Terminal capabilities](https://pkg.go.dev/github.com/cli/go-gh/v2/pkg/term) are determined by taking environment variables `GH_FORCE_TTY`, `NO_COLOR`, `CLICOLOR`, etc. into account.
12
13- Generating [table](https://pkg.go.dev/github.com/cli/go-gh/v2/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template) output uses the same engine as gh.
14
15- The [`browser`](https://pkg.go.dev/github.com/cli/go-gh/v2/pkg/browser) module activates the user's preferred web browser.
16
17## Usage
18
19See the full `go-gh` [reference documentation](https://pkg.go.dev/github.com/cli/go-gh/v2) for more information
20
21```golang
22package main
23
24import (
25 "fmt"
26 "log"
27 "github.com/cli/go-gh/v2"
28 "github.com/cli/go-gh/v2/pkg/api"
29)
30
31func main() {
32 // These examples assume `gh` is installed and has been authenticated.
33
34 // Shell out to a gh command and read its output.
35 issueList, _, err := gh.Exec("issue", "list", "--repo", "cli/cli", "--limit", "5")
36 if err != nil {
37 log.Fatal(err)
38 }
39 fmt.Println(issueList.String())
40
41 // Use an API client to retrieve repository tags.
42 client, err := api.DefaultRESTClient()
43 if err != nil {
44 log.Fatal(err)
45 }
46 response := []struct{
47 Name string
48 }{}
49 err = client.Get("repos/cli/cli/tags", &response)
50 if err != nil {
51 log.Fatal(err)
52 }
53 fmt.Println(response)
54}
55```
56
57See [examples][] for more demonstrations of usage.
58
59## Contributing
60
61If anything feels off, or if you feel that some functionality is missing, please check out our [contributing docs][contributing]. There you will find instructions for sharing your feedback and for submitting pull requests to the project. Thank you!
62
63[extensions]: https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions
64[examples]: ./example_gh_test.go
65[contributing]: ./.github/CONTRIBUTING.md
View as plain text