gastownhall/beads · error

gh CLI not installed

Error message

gh CLI not installed

What it means

Returned by checkGHRunStatusInRepoWithRunner when the `gh` executable cannot be found (cmd/bd/gate.go:1074). It detects 'command not found' in stderr or 'executable file not found' in the runner error and reports that the GitHub CLI is missing rather than a gh-level failure.

Source

Thrown at cmd/bd/gate.go:1074

	return checkGHRunStatusInRepo(runID, "")
}

func checkGHRunStatusInRepo(runID, repo string) (resolved, escalated bool, reason string, err error) {
	return checkGHRunStatusInRepoWithRunner(runID, repo, runGHCommand)
}

func checkGHRunStatusInRepoWithRunner(runID, repo string, runGH ghCommandRunner) (resolved, escalated bool, reason string, err error) {
	// Run: gh run view <id> --json status,conclusion,name
	args := []string{"run", "view", runID, "--json", "status,conclusion,name"}
	if repo != "" {
		args = append(args, "--repo", repo)
	}
	stdout, stderr, runErr := runGH(args...)
	if runErr != nil {
		// Check if gh CLI is not found
		if strings.Contains(string(stderr), "command not found") ||
			strings.Contains(runErr.Error(), "executable file not found") {
			return false, false, "", fmt.Errorf("gh CLI not installed")
		}
		// Check if run not found
		if strings.Contains(string(stderr), "not found") {
			return false, true, "workflow run not found", nil
		}
		return false, false, "", fmt.Errorf("gh run view failed: %s", string(stderr))
	}

	var status ghRunStatus
	if parseErr := json.Unmarshal(stdout, &status); parseErr != nil {
		return false, false, "", fmt.Errorf("failed to parse gh output: %w", parseErr)
	}

	// Evaluate status
	switch status.Status {
	case "completed":
		switch status.Conclusion {
		case "success":

View on GitHub (pinned to 71377f2769)

Solutions

1. Install the GitHub CLI (https://cli.github.com) e.g. `brew install gh` or the apt/deb package
2. Verify `which gh` / `gh --version` works in the same environment bd runs in
3. Fix PATH for the service user/daemon so the gh binary is discoverable
4. Ensure `gh auth login` was completed after install

Example fix

// before (CI container)
# no gh
// after
RUN apt-get update && apt-get install -y gh && gh auth login --with-token

if _, err := exec.LookPath("gh"); err != nil {
    return errors.New("gh CLI must be installed and on PATH before using gh:run gates")
}

if _, _, _, err := checkGHRun(gate); err != nil && err.Error() == "gh CLI not installed" {
    // fail fast with install instructions; do not retry
}

When it happens

Trigger: A gh:run gate is evaluated and runGH fails because the `gh` binary is absent from PATH (not installed, wrong PATH in the service/agent environment).

Common situations: CI container or server without gh installed, PATH not set for daemonized processes, gh installed via a version manager whose shims aren't on the service PATH.

Related errors

• dolt CLI not found (required for remote bootstrap): %w
• unable to determine home directory: %w
• bd binary not found in PATH: %w
• not a git repository
• %s

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