Skip to content
Skills Library
Programming · Research

gh-cli

/gh-cli

GitHub CLI for remote repository analysis, file fetching, codebase comparison, and discovering trending code/repos. Use when analyzing repos without cloning, comparing codebases, or searching for popular GitHub projects.

Repository
skills ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
16
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

GitHub CLI for remote repository analysis, file fetching, codebase comparison, and discovering trending code/repos. Use when analyzing repos without cloning, comparing codebases, or searching for popular GitHub projects.

Original author description

GitHub CLI for remote repository analysis, file fetching, codebase comparison, and discovering trending code/repos. Use when analyzing repos without cloning, comparing codebases, or searching for popular GitHub projects.

How it works

  1. When to Use
  2. Quick Operations
  3. Compare Two Codebases
  4. Discover Trending Content
  5. Search Basics
  6. Special Syntax
  7. Scripting Gotchas
  8. Preview Commands
  9. Advanced Workflows
  10. Resources
Original SKILL.md headings · 350 lines, 1,962 words
SKILL.md preview
---
name: gh-cli
description: GitHub CLI for remote repository analysis, file fetching, codebase comparison, and discovering trending code/repos. Use when analyzing repos without cloning, comparing codebases, or searching for popular GitHub projects.
metadata:
  version: "1.4.0"
  categories: "development, integrations"
  topics: "github, gh-cli, code-search, repo-analysis, pull-requests"
  upstream: "gh@2.101.0"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/gh-cli
    emoji: "🐙"
    primaryEnv: GH_TOKEN
    requires:
      bins:
        - gh
    install:
      - kind: brew
        formula: gh
        bins:
          - gh
    envVars:
      - name: GH_TOKEN
        required: false
        description: GitHub auth token used by gh CLI.
      - name: GITHUB_TOKEN
        required: false
        description: Alias for GH_TOKEN.
      - name: GH_HOST
        required: false
        description: GitHub Enterprise host override.
---

# GitHub CLI - Remote Analysis & Discovery

Remote repository operations, codebase comparison, and code discovery without cloning.

## When to Use

- Analyze repositories without cloning
- Compare codebases side-by-side
- Fetch specific files from any repo
- Find trending repositories and code patterns
- Search code across GitHub

## Quick Operations

### Fetch a file remotely

```bash
gh repo read-file path/file.ts --repo OWNER/REPO
```

`gh repo read-file` (preview) is the preferred path: it prints raw content, takes `--ref` for any branch/tag/commit, and handles large files. `--output PATH` writes to disk (`--clobber` to overwrite); `--json` returns metadata (`content, downloadUrl, encoding, gitSHA, gitUrl, htmlUrl, name, path, size, type, url`). Fall back to `gh api` where the command is unavailable:

```bash
gh api repos/OWNER/REPO/contents/path/file.ts -H "Accept: application/vnd.github.raw"
```

There is **no `base64decode` template function** - `--template '{{.content | base64decode}}'` fails with `function "base64decode" not defined`. To decode the default JSON response, pipe it:

```bash
gh api repos/OWNER/REPO/contents/path/file.ts --jq '.content' | base64 -d
```

The Contents API inlines only files up to **1MB**. Past that, `.content` is an empty string (`encoding: "none"`) and the pipe above silently prints nothing - use `read-file` or the raw `Accept` header instead.

### Terminal escape sequences (gh 2.97.0+)

`gh` refuses to print remote content containing terminal escape sequences (ANSI art, some test fixtures) instead of passing it to your terminal:

- `gh repo read-file`: `file contains terminal escape sequences; use --allow-escape-sequences to read anyway`
- `gh api` raw bodies: `the response contains terminal escape sequences; pass --allow-escape-sequences to output it anyway`
- `gh pr diff` when piped: `the diff contains terminal escape sequences; pass --allow-escape-sequences to output it anyway`

Pass `--allow-escape-sequences` (also on `gh release download --output -` and `gh gist view`) when you need the bytes verbatim, or write to disk with `gh repo read-file --output`, which always keeps the raw bytes. The check came with the GHSA-3m3g-3wcr-px46 fix; run gh 2.98.0 or later to get it and the other 2.97/2.98 security fixes.

### Get directory listing

```bash
gh repo read-dir PATH --repo OWNER/REPO    # omit PATH to list the repo root

# Or via the API
gh api repos/OWNER/REPO/contents/PATH
```

`gh repo read-dir --json` returns an object, not an array - `{"entries":[...]}` - so filter with `.entries[]`:

```bash
gh repo read-dir src --repo OWNER/REPO --json name,type --jq '.entries[] | select(.type=="file") | .name'
```

### Pin the repo in scripted workflows

`gh` infers the repository from the current working directory. In agent or CI workflows - where a `cd` may persist - always pass `--repo OWNER/REPO` so a stray cwd cannot silently retarget the command. Signatures of a missing `--repo`:

- Outside a git repo: `failed to run git: fatal: not a git repository`
- In a repo with no remote: `no git remotes found`
- Inside a *different* repo: no error - the command targets that repo, and IDs from elsewhere 404

### Search code

```bash
gh search code "pattern" --language=typescript
```

### Find trending repos

```bash
gh search repos --language=rust --sort stars --order desc
```

## Compare Two Codebases

Systematic workflow for comparing repositories to identify similarities and differences.

**Example use**: "Compare solana-fm/explorer-kit and tenequm/solana-idls"

### Step 1: Fetch directory structures

```bash
gh repo read-dir PATH --repo OWNER-A/REPO-A
gh repo read-dir PATH --repo OWNER-B/REPO-B
```

If comparing a monorepo package, specify the path (e.g., `packages/explorerkit-idls`).

### Step 2: Compare file lists

```bash
diff <(gh repo read-dir PATH --repo OWNER-A/REPO-A --json name --jq '.entries[].name') \
     <(gh repo read-dir PATH --repo OWNER-B/REPO-B --json name --jq '.entries[].name')
```

Lines prefixed `<` exist only in repo A, `>` only in repo B.

### Step 3: Fetch key files for comparison

Compare package dependencies:

```bash
gh repo read-file package.json --repo OWNER-A/REPO-A
gh repo read-file package.json --repo OWNER-B/REPO-B
```

Compare main entry points:

```bash
gh repo read-file src/index.ts --repo OWNER-A/REPO-A
gh repo read-file src/index.ts --repo OWNER-B/REPO-B
```

Add `--cache 1h` to `gh api` calls when iterating on the same files repeatedly, to avoid re-spending rate limit.

Comparing two refs of the **same** repo (or a fork of it) is one call to the compare API, capped at 250 commits and 300 files:

```bash
gh api repos/OWNER/REPO/compare/v1.0.0...v2.0.0 --jq '{ahead_by, files: [.files[].filename]}'
```

### Step 4: Analyze differences

Compare the fetched files to identify:

**API Surface**
- What functions/classes are exported?
- Are the APIs similar or completely different?

**Dependencies**
- Shared dependencies (same approach)
- Different dependencies (different implementation)

**Unique Features**
- Features only in repo1
- Features only in repo2

For detailed comparison strategies, see [references/comparison.md](references/comparison.md).

## Discover Trending Content

### Find trending repositories

```bash
# Most starred repos - a bare `--sort` with no query or filter flag fails: Invalid search query ""
gh search repos "stars:>10000" --sort stars --order desc --limit 20

# Trending in specific language
gh search repos --language=rust --sort stars --order desc

# Recently popular (created in the last 30 days; works with BSD and GNU date)
SINCE=$(date -v-30d +%F 2>/dev/null || date -d '30 days ago' +%F)
gh search repos "created:>$SINCE" --sort stars --order desc

# Trending in specific topic
gh search repos "topic:machine-learning" --sort stars --order desc
```

### Discover popular code patterns

```bash
# Find popular implementations (code search has no sorting - scope with filters)
gh search code "function useWallet" --language=typescript

# Scope to a known repo (code search can't filter by stars - stars:>N is literal text)
gh search code "implementation" --repo=honojs/hono

# Search specific organization
gh search code "authentication" --owner=anthropics
```

For complete discovery queries and patterns, see [references/discovery.md](references/discovery.md).

## Search Basics

### Code search

```bash
# Search across all repositories
gh search code "API endpoint" --language=python

# Search in specific organization
gh search code "auth" --owner=anthropics

# Exclude results with negative qualifiers
gh search issues -- "bug report -label:wontfix"
```

### Issue & PR search

```bash
# Find open bugs (--state takes only open|closed here; omit it for both)
gh search issues --label=bug --state=open

# Search assigned issues
gh search issues --assignee=@me --state=open

# Meaning-based issue search (gh 2.98.0+): relevance-ranked, issues only, one page, no --sort/--order
gh search issues worktree checkout --repo cli/cli --search-type hybrid
```

Separate words are ANDed. A single quoted multi-word argument is sent as an **exact phrase**, so `gh search issues "worktree checkout"` can return nothing with exit 0.

### Search rate limits

Search runs on a much tighter budget than the 5000/hr core API - check with `gh api rate_limit`:

| Resource | Limit (authenticated) |
|----------|----------------------|
| `core` (incl. `gh api`, `gh repo read-file`) | 5000/hr |
| `search` (repos, issues, prs, commits) | 30/min |
| `code_search` | 10/min |
| `semantic_search` (`--search-type semantic\|hybrid`) | 10/min - not listed by `gh api rate_limit` |

For advanced search syntax, see [references/search.md](references/search.md).

## Special Syntax

### Field name inconsistencies

**IMPORTANT:** GitHub CLI uses inconsistent field names across commands:

| Field | `gh repo view` | `gh search repos` |
|-------|----------------|-------------------|
| Stars | `stargazerCount` | `stargazersCount` |
| Forks | `forkCount` | `forksCount` |
| Topics | `repositoryTopics` | not available |
| Watchers | `watchers` (`{totalCount}`) | `watchersCount` - actually the star count |

**Examples:**

```bash
# ✅ Correct for gh repo view
gh repo view owner/repo --json stargazerCount,forkCount

# ✅ Correct for gh search repos
gh search repos "query" --json stargazersCount,forksCount
```

Other fields that do not exist where you expect them: `gh pr view` has no `merged` (use `mergedAt` or `state`), `gh search prs` has no `mergedAt` (use `closedAt`), and `gh run list` has no `jobs` (use `gh run view <id> --json jobs`). A wrong field fails with `Unknown JSON field: "X"` followed by the valid list.

### One qualifier per argument

`gh search` (gh 2.97.0+) splits each argument at its **first** `:` and wraps the rest in quotes if it contains a space. Packing several qualifiers into one quoted string silently breaks the filter:

```bash
# ❌ Sent as language:"go stars:>500" - the language filter is lost
gh search repos "rate limiting middleware language:go stars:>500"

# ✅ Keywords and qualifiers as separate arguments; quote only those containing > or <
gh search repos rate limiting middleware language:go "stars:>500"
```

`gh pr list --search` and `gh issue list --search` pass their string through untouched, so one quoted string is fine there.

### Excluding search results

A negative qualifier works as its own argument or at the end of a quoted string (`"bug report -label:wontfix"`). `--` is only required when the query *starts* with a hyphen, which the shell would otherwise read as a flag.

**Put every flag before `--`.** Everything after `--` is positional, so trailing flags get swallowed into the query string:

```bash
# ✅ Correct - flags first
gh search issues --limit 5 -- -label:wontfix bug

# ❌ Wrong - --limit 5 becomes part of the search query, silently returning 30 results
gh search issues -- -label:wontfix bug --limit 5
```

For more syntax gotchas, see [references/syntax.md](references/syntax.md).

## Scripting Gotchas

- **Every command needs auth** - without a token `gh` prints `please run:  gh auth login` and exits 4. The exception is `gh release download` on public repos.
- **`gh api` writes its error body to stdout.** On failure it exits 1, prints `gh: Not Found (HTTP 404)` to stderr, and prints the error JSON to stdout without applying `--jq`. `$(gh api ...)` then captures the error as if it were data, so check the exit status:

  ```bash
  if sha=$(gh api repos/OWNER/REPO/contents/README.md --jq .sha); then echo "$sha"; else echo "fetch failed" >&2; fi
  ```

- **`-f`/`-F` switch `gh api` to POST**, so GET-only endpoints answer 404. Add `-X GET` to send the fields as a query string:

  ```bash
  gh api -X GET search/issues -f q='repo:cli/cli is:open worktree' --jq '.total_count'
  ```

- **`--jq` takes one expression and no jq flags** (a trailing `-r` fails with `unknown shorthand flag: 'r'`); string results already print raw.
- **`--paginate --slurp` cannot combine with `--jq`/`--template`.** Pipe to `jq` instead, or use `--paginate --jq`, which filters each page.
- **Quote endpoints containing `?`** - zsh treats an unquoted `?` as a glob and fails with `no matches found`.
- **Exit codes** (`gh help exit-codes`): 0 success, 1 failure, 2 cancelled, 4 authentication required. Some commands add their own: `gh pr checks` exits 8 while checks are pending.

## Preview Commands

Recent `gh` releases added preview commands relevant to remote analysis and discovery. They are subject to change without notice.

```bash
# Read a repo without cloning (see Quick Operations above)
gh repo read-file PATH --repo OWNER/REPO
gh repo read-dir PATH --repo OWNER/REPO

# GitHub Discussions - often where design rationale lives
gh discussion list --repo OWNER/REPO --search "keyword" --answered
gh discussion view <number> --repo OWNER/REPO --comments

# Agent skills on GitHub
gh skill search <query>
gh skill preview OWNER/REPO <skill>    # print SKILL.md without installing
gh skill install OWNER/REPO <skill>
```

`gh discussion list --json` returns `{"discussions":[...],"next":...,"totalCount":...}`, so filter with `--jq '.discussions[].title'`. `gh discussion view` also accepts a comment URL (`.../discussions/123#discussioncomment-456`) to show one full reply thread, and `--comments` cannot be combined with `--json`.

`gh pr revert <number>` (opens a PR reverting a merged PR) is a regular command, not a preview - see [pull_requests.md](references/pull_requests.md).

## Advanced Workflows

For detailed documentation on specific workflows:

**Core Workflows:**
- [remote-analysis.md](references/remote-analysis.md) - Advanced file fetching patterns
- [comparison.md](references/comparison.md) - Complete codebase comparison guide
- [discovery.md](references/discovery.md) - All trending and discovery queries
- [search.md](references/search.md) - Advanced search syntax
- [syntax.md](references/syntax.md) - Special syntax and command quirks

**GitHub Operations:**
- [repositories.md](references/repositories.md) - Repository operations
- [pull_requests.md](references/pull_requests.md) - PR workflows, CI checks, review threads
- [issues.md](references/issues.md) - Issue management
- [actions.md](references/actions.md) - GitHub Actions, run attempts, reruns
- [releases.md](references/releases.md) - Release management

**Setup & Configuration:**
- [getting_started.md](references/getting_started.md) - `gh auth setup-git` credential helper
- [other.md](references/other.md) - Environment variables, auth traps, aliases, config
- [extensions.md](references/extensions.md) - CLI extensions

## Resources

- Official docs: https://cli.github.com/manual/
- GitHub CLI: https://github.com/cli/cli
- Search syntax: https://docs.github.com/en/search-github
Files in this package (16)
  • CHANGELOG.md 9 KB
  • LICENSE.txt 9 KB
  • SKILL.md 14 KB
  • references/actions.md 15 KB
  • references/comparison.md 6 KB
  • references/discovery.md 10 KB
  • references/extensions.md 2 KB
  • references/getting_started.md 1 KB
  • references/issues.md 11 KB
  • references/other.md 39 KB
  • references/pull_requests.md 19 KB
  • references/releases.md 7 KB
  • references/remote-analysis.md 5 KB
  • references/repositories.md 71 KB
  • references/search.md 14 KB
  • references/syntax.md 16 KB

Versions

RepositoryScoreLicence
This page · tenequm/skills100MIT
trailofbits/skills100CC-BY-SA-4.0
caarlos0/dotfiles100MIT
yamcodes/arkenv100MIT
benchflow-ai/skillsbench100Apache-2.0
farm-fe/farm100MIT
hamsurang/kit100MIT
fredrikaverpil/dotfiles95MIT
oleg-koval/agent-skills91MIT

Database snapshot: 13.11.2026 · package version 68635122d193 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95gh-trending-cli
    Use cli-web-gh-trending to answer questions about GitHub Trending — trending repositories, trending developers, filtering by programming language (python, javascript, typescript, rust, go, etc.), time ranges (daily, weekly, monthly), and spoken language. Invoke this skill…
  • 100gh-trending-cli
    Lists GitHub Trending repositories and developers via cli-web-gh-trending, with filters for programming language, time range (daily, weekly, monthly), and spoken language. Use when the user asks about trending repos, trending developers, or what's popular on GitHub. Prefer…
  • 95github-cli
    MUST USE for GitHub-related operations, including a GitHub URL, repository or code search, Issues, pull requests, Actions, Releases, permissions, and API requests. Use the local GitHub CLI (`gh`).
  • 95gh-helper
    Complete GitHub operations via gh CLI - repos, issues, PRs, code search, releases, file management When user mentions GitHub, repositories, issues, PRs, gh command, code search, commits, file contents
  • 100readme-generation
    Generate a professional README.md for a project. Works on local codebases and remote GitHub repos. Use when a project needs a README, when an existing README is outdated, or when documenting someone else's tool.
  • 100github-multi-repo
    Multi-repository coordination, synchronization, and architecture management across many GitHub repos. Use when changes span several repositories, keeping repos in sync, or planning cross-repo architecture and dependency work.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.