pi-gh-cli

Structured GitHub CLI tools for Pi agents

Packages

Package details

extension

Install pi-gh-cli from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-gh-cli
Package
pi-gh-cli
Version
0.2.5
Published
Jun 2, 2026
Downloads
1,021/mo · 47/wk
Author
tianrendong
License
MIT
Types
extension
Size
66.1 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-gh-cli

Structured GitHub CLI (gh) tools for Pi agents.

Install

pi install npm:pi-gh-cli

Or try without installing:

pi -e npm:pi-gh-cli

Requires GitHub CLI:

gh auth login

Tools (Layer 1 primitives)

One tool per GitHub resource. Agent owns orchestration.

  • gh_issue — list/view/create/comment/edit/close/reopen issues
  • gh_pr — list/view/checks/diff/create/comment/review/merge/close/reopen/ready/checkout/update_branch PRs
  • gh_repo — view/list/default/create/edit repositories
  • gh_run — list/view/watch/rerun/cancel/download GitHub Actions runs
  • gh_workflow — list/view/run/enable/disable workflows
  • gh_release — list/view/create/edit/delete/upload/download releases
  • gh_label — list/create/edit/delete/clone labels
  • gh_search — repos/issues/prs/code/commits search
  • gh_secret — list/set/delete Actions/Codespaces/Dependabot secrets
  • gh_variable — list/get/set/delete Actions variables
  • gh_gist — list/view/create/edit/delete/clone gists
  • gh_api — escape-hatch authenticated gh api requests (REST + GraphQL)
  • gh_auth_status — read-only auth check, never shows tokens

Result envelope

Each tool returns:

  • content[0].text — formatted stdout (JSON pretty-printed when possible)
  • details.command — full gh argv
  • details.parsed — parsed JSON if applicable
  • details.actionClass — read | local_mutation | github_mutation | destructive
  • details.warnings — e.g. missing repo on mutation, unread pagination
  • details.nextSuggested — hints for follow-up calls
  • details.fullOutputPath — set when truncated

Safety

  • Argument arrays, no shell quoting.
  • Defaults to gh --json fields where available; pass fields= to override.
  • Tools never request interactive confirmation. State-changing actions run non-interactively when invoked.
  • Prompt-prone actions validate required args or pass blank bodies/notes rather than opening editors.
  • Destructive actions (delete) auto-pass --yes; caller intent gates tool invocation.
  • Each gh process has a bounded timeout. Full output saved to a temp file when truncated.
  • Bodies/notes/secrets accept bodyFile / notesFile to avoid shell quoting and accidental logging.

Agent usage patterns

Read before write:

  1. gh_pr action=view with fields=number,title,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup,headRefOid
  2. Decide based on returned state.
  3. gh_pr action=merge with mergeMethod=squash and matchHeadCommit=<headRefOid>.

Always pass repo=OWNER/REPO for mutations to avoid current-directory inference.

For endpoints not covered, use gh_api. Prefer the typed tool when available.

Examples

Ask Pi:

List open PRs in this repo

Show failed logs for latest failing Actions run

Comment on issue #123 with this summary

For GitHub endpoints not covered by the specific tools, use gh_api.