" --body "<body>" --base main # body supports markdown; can also read from a file: --body-file pr.md # add reviewers/assignees/labels: gh pr create --title "..." --body "..." --reviewer alice,bob --label "needs review" --assignee @me ``` The opencode convention: only open PRs when the user explicitly asks. Inspect `git status`, `git diff`, and `git log --oneline -10` first, and stage only intended files. ### Review and merge ```bash gh pr view <N> # PR details, checks, mergeable state gh pr view <N> --comments # read the discussion gh pr diff <N> # the diff in the terminal gh pr checks <N> # CI status gh pr review <N> --approve --body "lgtm" gh pr review <N> --request-changes --body "please fix X" gh pr merge <N> --squash --delete-branch # --merge / --squash / --rebase match repo allowed methods # --auto waits for required checks before merging ``` ### List and filter ```bash gh pr list --author @me --state open gh pr list --search "review-requested:@me" gh issue list --assignee @me --state open gh pr list --state closed --limit 5 ``` ### Issues ```bash gh issue create --title "..." --body "..." --label bug --assignee @me gh issue view <N> gh issue close <N> gh issue comment <N> --body "..." ``` ### Releases ```bash gh release create v1.2.3 --notes "..." --title "v1.2.3" gh release create v1.2.3 ./dist/* # attach build artifacts gh release list gh release view v1.2.3 gh release download v1.2.3 ``` ### Repo metadata & browsing ```bash gh repo view # current repo info gh repo view owner/repo # another repo gh repo clone owner/repo gh repo create <name> --private --source=. --push # create + push cwd gh repo fork owner/repo --clone ``` ### Cross-repo / search ```bash gh search prs --author @me --state open gh search issues "is:open label:bug" gh search repos "topic:local-llm" ``` ## Aliases (optional quality-of-life) ```bash gh alias set co 'pr checkout' gh alias set rv 'pr review --view' # then: gh co 123 → gh pr checkout 123 ``` ## When to use - "Open a PR for this branch" / "merge it" / "what's the status of PR #123" - "Review the latest PR" / "request changes on #45" - "List my open issues" / "create an issue for this bug" - "Cut a release" / "attach these binaries to v2.0" - Any GitHub action where the agent would otherwise say "go to the web UI" ## When NOT to use - Reading the repo's source code → use Read/Glob/Grep on the working copy, not `gh` - Git operations (commit, push, branch) → use `git` directly; `gh` wraps GitHub, not git - Long-form PR body authoring → write to a file first, pass `--body-file` ## Auth troubleshooting - `gh auth status` fails → run `gh auth login` again, or confirm `GH_TOKEN` is exported in the shell. - "could not find any releases" on a fork → releases live on the upstream repo; use `gh release list --repo owner/repo`. - 403 on merge → the token lacks `pull-requests: write` (or repo `contents: write`); regenerate with the scope and re-login. ## Source Referenced in https://x.com/heyshruti7/status/2069083108092350823 — "GitHub CLI — open PRs, review, merge. Your agent never touches the web UI."

--- name: github-cli description: Use when the user asks to open a PR, review or merge a PR, list/check/review issues, react to or comment on PRs, create/manage releases, browse a repo's metadata, or do any GitHub operation without opening the web UI. Triggers on keywords like "gh", "GitHub CLI", "open a PR", "merge the PR", "review request", "list my PRs", "create release". Installs and drives the `gh` CLI so the agent never needs the browser for GitHub workflows. --- # GitHub CLI (`gh`) — GitHub without the web UI The agent should open PRs, review, merge, and manage issues/releases from the terminal instead of telling the user to "go to GitHub and click merge." ## Install (first use) If `gh` is not on PATH: ```bash brew install gh # macOS # or: sudo apt install gh # Debian/Ubuntu # or: winget install GitHub.cli # Windows ``` Authenticate (one-time): ```bash gh auth login # choose GitHub.com → HTTPS → "Login with a web browser" # or use a token: echo "$GH_TOKEN" | gh auth login --with-token ``` Verify: `gh auth status`. If automation is needed and interactive login isn't possible, set `GH_TOKEN` (or `GITHUB_TOKEN`) env var from a fine-grained PAT with the repo scopes needed (contents, pull-requests, workflows, issues). ## Core workflows ### Open a PR from the current branch ```bash gh pr create --title "" --body "<body>" --base main # body supports markdown; can also read from a file: --body-file pr.md # add reviewers/assignees/labels: gh pr create --title "..." --body "..." --reviewer alice,bob --label "needs review" --assignee @me ``` The opencode convention: only open PRs when the user explicitly asks. Inspect `git status`, `git diff`, and `git log --oneline -10` first, and stage only intended files. ### Review and merge ```bash gh pr view <N> # PR details, checks, mergeable state gh pr view <N> --comments # read the discussion gh pr diff <N> # the diff in the terminal gh pr checks <N> # CI status gh pr review <N> --approve --body "lgtm" gh pr review <N> --request-changes --body "please fix X" gh pr merge <N> --squash --delete-branch # --merge / --squash / --rebase match repo allowed methods # --auto waits for required checks before merging ``` ### List and filter ```bash gh pr list --author @me --state open gh pr list --search "review-requested:@me" gh issue list --assignee @me --state open gh pr list --state closed --limit 5 ``` ### Issues ```bash gh issue create --title "..." --body "..." --label bug --assignee @me gh issue view <N> gh issue close <N> gh issue comment <N> --body "..." ``` ### Releases ```bash gh release create v1.2.3 --notes "..." --title "v1.2.3" gh release create v1.2.3 ./dist/* # attach build artifacts gh release list gh release view v1.2.3 gh release download v1.2.3 ``` ### Repo metadata & browsing ```bash gh repo view # current repo info gh repo view owner/repo # another repo gh repo clone owner/repo gh repo create <name> --private --source=. --push # create + push cwd gh repo fork owner/repo --clone ``` ### Cross-repo / search ```bash gh search prs --author @me --state open gh search issues "is:open label:bug" gh search repos "topic:local-llm" ``` ## Aliases (optional quality-of-life) ```bash gh alias set co 'pr checkout' gh alias set rv 'pr review --view' # then: gh co 123 → gh pr checkout 123 ``` ## When to use - "Open a PR for this branch" / "merge it" / "what's the status of PR #123" - "Review the latest PR" / "request changes on #45" - "List my open issues" / "create an issue for this bug" - "Cut a release" / "attach these binaries to v2.0" - Any GitHub action where the agent would otherwise say "go to the web UI" ## When NOT to use - Reading the repo's source code → use Read/Glob/Grep on the working copy, not `gh` - Git operations (commit, push, branch) → use `git` directly; `gh` wraps GitHub, not git - Long-form PR body authoring → write to a file first, pass `--body-file` ## Auth troubleshooting - `gh auth status` fails → run `gh auth login` again, or confirm `GH_TOKEN` is exported in the shell. - "could not find any releases" on a fork → releases live on the upstream repo; use `gh release list --repo owner/repo`. - 403 on merge → the token lacks `pull-requests: write` (or repo `contents: write`); regenerate with the scope and re-login. ## Source Referenced in https://x.com/heyshruti7/status/2069083108092350823 — "GitHub CLI — open PRs, review, merge. Your agent never touches the web UI."