{"record":{"id":"fd248657e2dd8555","repo":"mastra-ai/mastra","slug":"github-cli-is-required-to-install-github-plugins","errorCode":null,"errorMessage":"GitHub CLI is required to install GitHub plugins. Install gh and run gh auth login.","messagePattern":"GitHub CLI is required to install GitHub plugins\\. Install gh and run gh auth login\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/plugins/install.ts","lineNumber":213,"sourceCode":"): Promise<void> {\n  const child = execa(command, args, {\n    ...execaOptions,\n    stdout: options.onOutput ? 'pipe' : 'ignore',\n    stderr: options.onOutput ? 'pipe' : 'ignore',\n    cancelSignal: options.signal,\n  });\n  if (options.onOutput) {\n    child.stdout?.on('data', options.onOutput);\n    child.stderr?.on('data', options.onOutput);\n  }\n  await child;\n}\n\nasync function assertGithubCliAvailable(githubCli: string): Promise<void> {\n  try {\n    await execa(githubCli, ['--version'], NON_INTERACTIVE_EXEC_OPTIONS);\n  } catch {\n    throw new Error('GitHub CLI is required to install GitHub plugins. Install gh and run gh auth login.');\n  }\n}\n\nasync function assertGithubCliAuthenticated(githubCli: string): Promise<void> {\n  try {\n    await execa(githubCli, ['auth', 'status'], NON_INTERACTIVE_EXEC_OPTIONS);\n  } catch {\n    throw new Error('GitHub CLI is not authenticated. Run gh auth login, then install the plugin again.');\n  }\n}\n\nfunction parseGithubUrl(specifier: string): { owner: string; repo: string; repoSpec: string; ref?: string } {\n  const [urlPart, ref] = specifier.split('#', 2);\n  if (!urlPart) {\n    throw new Error(`Invalid GitHub URL: ${specifier}`);\n  }\n  let url: URL;\n  try {","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/plugins/install.ts#L195-L231","documentation":"Installing plugins from GitHub requires the GitHub CLI (`gh`) for cloning/authenticated repository access. assertGithubCliAvailable runs `gh --version` non-interactively before any install work; any failure (binary missing, spawn error) becomes this single actionable error.","triggerScenarios":"Calling installGithubPlugin when `execa(githubCli, ['--version'])` throws — typically because `gh` is not installed or not on PATH of the process environment.","commonSituations":"Fresh machines/CI images without gh; gh installed via snap/desktop app but not on PATH; restricted PATH in systemd or GUI-launched processes; wrong executable name override in config.","solutions":["Install the GitHub CLI (e.g. `brew install gh`, `apt install gh`, or winget) and retry.","Verify `gh --version` works in the same shell/environment running the SDK.","Fix PATH so the gh binary directory is included for the process environment.","If the plugin is available locally, install it via a local path instead of a GitHub specifier."],"exampleFix":"// before\nmastra plugin install github:owner/repo   # gh missing\n\n// after\nbrew install gh && gh auth login\nmastra plugin install github:owner/repo","handlingStrategy":"try-catch","validationCode":"import { execFileSync } from 'node:child_process';\nexport function isGhInstalled(): boolean {\n  try { execFileSync('gh', ['--version'], { stdio: 'ignore' }); return true; }\n  catch { return false; }\n}\nif (!isGhInstalled()) throw new Error('Install the GitHub CLI before installing GitHub plugins');","typeGuard":null,"tryCatchPattern":"try {\n  await installGithubPlugin(spec);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('GitHub CLI is required')) {\n    console.error('Install gh (https://cli.github.com) and ensure it is on PATH.');\n  }\n  throw err;\n}","preventionTips":["Install gh in dev containers/CI base images as a standard dependency.","Check `which gh` in bootstrap scripts before running installs.","Document gh as a prerequisite alongside Node in the project README."],"tags":["github-cli","missing-binary","environment","plugins"],"backgroundTag":"command-not-found-gh","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}