---

name: github-cli category: core-infrastructure/development-tools version: 1.0.0 description: GitHub CLI authentication and GraphQL API usage for safe GitHub operations author: obra/superpowers verified: true tags: [github, cli, authentication, graphql, api, security]

Skill: GitHub CLI Auth + GraphQL Usage

<key_idea> Prefer gh auth login over manually managing PATs:

• gh stores credentials in your OS keychain (or gh's credential store) instead of committing anything
• Scripts can call gh api ... without exporting tokens to shell history </key_idea>

<recommended_auth_method> In order of preference:

1. GitHub CLI (gh auth login) for local agentic runs (best default)
2. GitHub App (best for team/server automation): short-lived tokens, fine-grained permissions, easy rotation
3. Fine-grained PAT if you must use a PAT (prefer over "classic")
4. Classic PAT only as a last resort (broad scopes; easier to over-grant) </recommended_auth_method>

<inputs_to_collect>

• Host: GitHub.com (default), or GitHub Enterprise Server (GHES) host (e.g. github.company.com)
• Access needs:
  • Public repos only, or private repos too?
  • Do you need org data (teams/repos in an org)?
• Environment:
  • macOS (Homebrew), Linux (apt/yum), Windows (winget/choco) </inputs_to_collect>

Linux (common)

If you already have gh installed:

gh --version

If not, install using your distro's package manager

or follow GitHub CLI install instructions for your distro

Windows

Use winget or Chocolatey, then confirm:

gh --version

Linux (example with xclip)

xclip -selection clipboard -o | gh auth login --with-token

• gh auth login --with-token reads the token from stdin
• For OSS discovery + GraphQL reads, you usually don't need extra scopes beyond defaults unless you hit a specific "resource not accessible" error

<typical_needs>

• Public-only discovery: usually fine by default
• Org metadata: may require read:org
• Private repos: may require repo </typical_needs>

<graphql_usage> Quick test: "Who am I?" gh api graphql -f query='query { viewer { login } }' <expected_output>

Copy{ "data": { "viewer": { "login": "your-handle" } } }

</expected_output>

Run it

gh api graphql -f query=@query.graphql -f login='your-handle'

Run a single page (50 results)

gh api graphql
-f query=@repo-search.graphql
-f q='topic:shopify-hydrogen stars:>50 archived:false'
-F first=50

Paginate (pass the previous endCursor)

gh api graphql
-f query=@repo-search.graphql
-f q='topic:headless-commerce stars:>100 archived:false'
-F first=50
-f endCursor='CURSOR_FROM_PREVIOUS_RESPONSE'

<integration_notes> <oss_discovery_workflow> Preferred local auth path:

• Login once: gh auth login
• Run discovery: ./.blackbox/scripts/start-oss-discovery-cycle.sh

Token fallback path (use only if needed):

Set GITHUB_TOKEN in your shell (from gh, without printing it)

export GITHUB_TOKEN="$(gh auth token)"

Run your scripts

./.blackbox/scripts/start-oss-discovery-and-curate.sh --owner "Shaan" --top 25 -- --min-stars 100

Optional cleanup

unset GITHUB_TOKEN </oss_discovery_workflow> </integration_notes>

<incident_response> If you accidentally pasted a token somewhere public:

1. Revoke it immediately in GitHub Settings → Developer settings → Personal access tokens
2. Assume it is compromised once exposed </incident_response>

<done_checklist>

• gh --version works
• gh auth status shows "Logged in"
• gh api graphql -f query='query { viewer { login } }' returns your login
• You can run the OSS discovery scripts without hitting immediate rate limits </done_checklist>