ghcli

Documentation

Overview

Package ghcli manages the discovery and installation of the real GitHub CLI (gh) binary. It provides resolution logic to find gh in managed locations, PATH, or by auto-downloading from the cli/cli GitHub releases.

Index

• Constants
• func CheckStaleness(resolvedPath string)
• func Download(destPath string) error
• func FindRealGHInPath() string
• func GetLatestVersion() (string, error)
• func InstalledVersion(ghPath string) (string, error)
• func IsManagedGH(resolvedPath string) bool
• func IsShim(ghPath string, ghxPath string) bool
• func ManagedGHPath() string
• func ResolveGHPath(cfgGHPath string) (string, error)
• func ShimContent() string
• func Upgrade(destPath string) (string, error)

Constants

const ShimMarker = "# ghx-shim"

ShimMarker is the comment marker embedded in gh shim scripts for detection.

const StalenessThreshold = 30 * 24 * time.Hour // 30 days

StalenessThreshold is how old a managed gh binary can be before a warning is shown.

Functions

func CheckStaleness

func CheckStaleness(resolvedPath string)

CheckStaleness prints a warning to stderr if the managed gh binary is older than StalenessThreshold. Only applies to the managed binary at ~/.ghx/bin/gh, not user-installed or PATH-resolved gh.

func Download

func Download(destPath string) error

Download downloads the GitHub CLI binary to destPath. It uses a lock file to prevent concurrent downloads, verifies checksums, and uses atomic file operations. Skips download if destPath already exists.

func FindRealGHInPath

func FindRealGHInPath() string

FindRealGHInPath searches PATH for a real gh binary, skipping ghx shims.

func GetLatestVersion

func GetLatestVersion() (string, error)

GetLatestVersion fetches the latest GitHub CLI version from the releases API.

func InstalledVersion

func InstalledVersion(ghPath string) (string, error)

InstalledVersion returns the version of the gh binary at the given path by running "gh --version" and parsing the output.

func IsManagedGH

func IsManagedGH(resolvedPath string) bool

IsManagedGH reports whether the resolved gh path points to the ghx-managed binary.

func IsShim

func IsShim(ghPath string, ghxPath string) bool

IsShim checks if the given ghPath is a ghx shim rather than the real GitHub CLI. It uses multiple detection strategies:

1. Resolved path / inode comparison (catches symlinks and hardlinks to ghx)
2. File header marker check (catches shell script shims)

func ManagedGHPath

func ManagedGHPath() string

ManagedGHPath returns the path where ghx manages its own gh binary (~/.ghx/bin/gh).

func ResolveGHPath

func ResolveGHPath(cfgGHPath string) (string, error)

ResolveGHPath finds the real GitHub CLI (gh) binary.

Resolution order:

1. User override — if cfgGHPath is not the default "gh", use it directly
2. PATH scan — search for a real gh in PATH, skipping ghx shims
3. Managed location — ~/.ghx/bin/gh (previously downloaded)
4. Auto-download — download from cli/cli releases to managed location

func ShimContent

func ShimContent() string

ShimContent returns the content for the gh shim shell script.

func Upgrade

func Upgrade(destPath string) (string, error)

Upgrade re-downloads the latest GitHub CLI to destPath, replacing any existing binary. Returns the installed version string.