What causes "gh CLI not found: install from https://cli.github.com" in gastownhall/beads?

Install the GitHub CLI: see https://cli.github.com (e.g. `brew install gh` or `apt install gh`)

gh CLI not found: install from https://cli.github.com

Error message

gh CLI not found: install from https://cli.github.com

What it means

queryGitHubRunsInRepo shells out to the GitHub `gh` CLI to list workflow runs. Before doing so it checks exec.LookPath("gh"); if the binary is not on PATH it returns this fixed message directing the user to install the CLI. bd does not call the GitHub API itself for gate discovery, so gh is a hard requirement.

Source

Thrown at cmd/bd/gate_discover.go:443

	output, err := cmd.Output()
	if err != nil {
		return ""
	}
	return strings.TrimSpace(string(output))
}

// queryGitHubRunsInRepo queries recent workflow runs from GitHub using gh
// CLI, scoped to repo ("" means the current repository) and optionally
// narrowed to a single workflow (workflow == "" queries all workflows). This
// is the query path for `bd gate discover`'s branch/heuristic matching (SF1)
// - distinct from queryGitHubRunsForWorkflowInRepo in gate.go, which filters
// by a specific --workflow name for the direct await_id discovery used by
// `bd gate check`. matchGatesToRuns only ever passes a non-empty workflow for
// a foreign repo, to recover the visibility --limit would otherwise cost an
// unfiltered cross-repo query (see matchGatesToRuns).
func queryGitHubRunsInRepo(branch string, limit int, repo string, workflow string) ([]GHWorkflowRun, error) {
	if _, err := exec.LookPath("gh"); err != nil {
		return nil, fmt.Errorf("gh CLI not found: install from https://cli.github.com")
	}
	return queryGitHubRunsInRepoWithRunner(branch, limit, repo, workflow, runGHCommand)
}

func queryGitHubRunsInRepoWithRunner(branch string, limit int, repo string, workflow string, runGH ghCommandRunner) ([]GHWorkflowRun, error) {
	args := []string{
		"run", "list",
		"--json", "databaseId,displayTitle,headBranch,headSha,name,status,conclusion,createdAt,updatedAt,workflowName,url",
		"--limit", strconv.Itoa(limit),
	}

	if branch != "" {
		args = append(args, "--branch", branch)
	}
	if repo != "" {
		args = append(args, "--repo", repo)
	}
	if workflow != "" {

View on GitHub (pinned to 71377f2769)

Solutions

Install the GitHub CLI: see https://cli.github.com (e.g. `brew install gh` or `apt install gh`)
Verify `which gh` resolves and `gh --version` works in the same shell where bd runs
If gh is installed elsewhere, add its directory to PATH in the environment running bd
Authenticate once with `gh auth login` so subsequent run-list queries succeed

Example fix

// before
$ bd gate discover
Error: gh CLI not found: install from https://cli.github.com
// after
$ brew install gh && gh auth login
$ bd gate discover

Defensive patterns

Strategy: validation

Validate before calling

if _, err := exec.LookPath("gh"); err != nil {
  return fmt.Errorf("gh CLI is required for gate discovery: install from https://cli.github.com")
}

Try / catch

runs, err := queryGitHubRunsInRepo(branch, limit, repo, workflow)
if err != nil && strings.Contains(err.Error(), "gh CLI not found") {
  return fmt.Errorf("install gh first: https://cli.github.com, then `gh auth login`")
}

Prevention

Install gh in every environment (dev, CI image, container) that runs bd gate commands
Pin gh in CI Dockerfiles and verify with `gh --version` in the entrypoint
Run `gh auth login` (or set GH_TOKEN) as part of machine setup
Check `which gh` in shell startup when bd commands mysteriously fail

When it happens

Trigger: Running `bd gate discover` (or `bd gate check` discovery paths) on a machine where the `gh` executable is not installed or is not on PATH (exec.LookPath fails).

Common situations: Fresh CI container or new laptop without gh installed; gh installed via a non-PATH location (e.g. manual download to ~/bin not on PATH); PATH differs between the user's shell and the environment running bd; Docker image missing the dependency.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/9ed52b74a81ce95c. Report an issue: GitHub.