gh

README

Go library for the GitHub CLI

go-gh is a collection of Go modules to make authoring GitHub CLI extensions easier.

Modules from this library will obey GitHub CLI conventions by default:

• repository.Current() respects the value of the GH_REPO environment variable and reads from git remote configuration as fallback.

• 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.

• Terminal capabilities are determined by taking environment variables GH_FORCE_TTY, NO_COLOR, CLICOLOR, etc. into account.

• Generating table or Go template output uses the same engine as gh.

• The browser module activates the user's preferred web browser.

Usage

See the full go-gh reference documentation for more information

package main

import (
	"fmt"
	"log"
	"github.com/cli/go-gh/v2"
	"github.com/cli/go-gh/v2/pkg/api"
)

func main() {
	// These examples assume `gh` is installed and has been authenticated.

	// Shell out to a gh command and read its output.
	issueList, _, err := gh.Exec("issue", "list", "--repo", "cli/cli", "--limit", "5")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(issueList.String())

	// Use an API client to retrieve repository tags.
	client, err := api.DefaultRESTClient()
	if err != nil {
		log.Fatal(err)
	}
	response := []struct{
		Name string
	}{}
	err = client.Get("repos/cli/cli/tags", &response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

See examples for more demonstrations of usage.

Contributing

If anything feels off, or if you feel that some functionality is missing, please check out our contributing docs. There you will find instructions for sharing your feedback and for submitting pull requests to the project. Thank you!

Documentation

Overview

Package gh is a library for CLI Go applications to help interface with the gh CLI tool, and the GitHub API.

Note that the examples in this package assume gh and git are installed. They do not run in the Go Playground used by pkg.go.dev.

Index

• func Exec(args ...string) (stdout, stderr bytes.Buffer, err error)
• func ExecContext(ctx context.Context, args ...string) (stdout, stderr bytes.Buffer, err error)
• func ExecInteractive(ctx context.Context, args ...string) error
• func Path() (string, error)

Examples

• Exec

Functions

func Exec

func Exec(args ...string) (stdout, stderr bytes.Buffer, err error)

Exec invokes a gh command in a subprocess and captures the output and error streams.

Example

Execute 'gh issue list -R cli/cli', and print the output.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh/v2"
)

func main() {
	args := []string{"issue", "list", "-R", "cli/cli"}
	stdOut, stdErr, err := gh.Exec(args...)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(stdOut.String())
	fmt.Println(stdErr.String())
}

func ExecContext

func ExecContext(ctx context.Context, args ...string) (stdout, stderr bytes.Buffer, err error)

ExecContext invokes a gh command in a subprocess and captures the output and error streams.

func ExecInteractive

func ExecInteractive(ctx context.Context, args ...string) error

Exec invokes a gh command in a subprocess with its stdin, stdout, and stderr streams connected to those of the parent process. This is suitable for running gh commands with interactive prompts.

func Path

func Path() (string, error)

Path searches for an executable named "gh" in the directories named by the PATH environment variable. If the executable is found the result is an absolute path.