zhongwei/gh-tenequm-claude-plugins-gh-cli

Fork 0

Files

Zhongwei Li 7f0944bcfe Initial commit

2025-11-30 09:01:17 +08:00

8.9 KiB

Raw Blame History

Special Syntax & Command Quirks

GitHub CLI has several syntax inconsistencies and special cases to be aware of.

Field Name Inconsistencies

CRITICAL: Different commands use different field names for the same data.

Stars field

Command	Field Name
`gh repo view`	`stargazerCount`
`gh search repos`	`stargazersCount`

Examples:

# ✅ Correct for gh repo view
gh repo view anthropics/anthropic-sdk-python --json stargazerCount

# ✅ Correct for gh search repos
gh search repos "anthropics" --json stargazersCount

# ❌ Wrong - will error
gh repo view anthropics/anthropic-sdk-python --json stargazersCount
gh search repos "anthropics" --json stargazerCount

Forks field

Command	Field Name
`gh repo view`	`forkCount`
`gh search repos`	`forksCount`

Examples:

# ✅ Correct
gh repo view owner/repo --json forkCount
gh search repos "query" --json forksCount

# ❌ Wrong
gh repo view owner/repo --json forksCount
gh search repos "query" --json forkCount

Quick reference table

Data	`gh repo view`	`gh search repos`
Stars	`stargazerCount`	`stargazersCount`
Forks	`forkCount`	`forksCount`
Topics	`repositoryTopics`	`repositoryTopics`
Description	`description`	`description`
URL	`url`	`url`

Negative Qualifiers

When using negative search qualifiers (prefixed with -), you need special syntax to prevent the shell from interpreting the hyphen as a flag.

Unix/Linux/Mac

Use -- to mark the end of flags:

# ✅ Correct
gh search issues -- "bug report -label:wontfix"
gh search repos -- "typescript -topic:deprecated"
gh search code -- "TODO -filename:test"

# ❌ Wrong - shell interprets -label as a flag
gh search issues "bug report -label:wontfix"

PowerShell

Use --% (stop parsing) operator:

# ✅ Correct
gh --% search issues -- "bug report -label:wontfix"
gh --% search repos -- "rust -archived:true"

# ❌ Wrong
gh search issues "bug report -label:wontfix"

Common negative qualifiers

# Exclude labels
gh search issues -- "bug -label:wontfix -label:duplicate"

# Exclude topics
gh search repos -- "web framework -topic:deprecated"

# Exclude archived repos
gh search repos -- "stars:>100 -archived:true"

# Exclude specific languages
gh search code -- "config -language:json"

# Exclude filenames
gh search code -- "authentication -filename:test -filename:spec"

Date Format Quirks

ISO 8601 format required

# ✅ Correct
gh search repos "created:>2024-10-01"
gh search repos "pushed:<2024-12-31"

# ❌ Wrong
gh search repos "created:>10/01/2024"  # US format doesn't work
gh search repos "created:>2024/10/01"  # Slashes don't work

Date ranges

# Between dates
gh search repos "created:2024-01-01..2024-06-30"

# Relative dates work in some contexts
gh search repos "pushed:>2024-10-01"  # After October 1st

# Time is optional (defaults to start of day)
gh search repos "created:>2024-10-01T12:00:00Z"  # With time
gh search repos "created:>2024-10-01"  # Without time (00:00:00)

Search Syntax Gotchas

Spaces in queries

Wrap multi-word queries in quotes:

# ✅ Correct
gh search code "error handling" --language=python
gh search repos "machine learning" --sort stars

# ❌ Wrong - treats each word as separate argument
gh search code error handling --language=python

Boolean operators

GitHub search doesn't support traditional AND/OR/NOT:

# ✅ Use qualifiers instead
gh search repos "topic:react topic:typescript"  # Implicit AND
gh search issues -- "bug -label:wontfix"  # Implicit NOT

# ❌ Wrong - literal text search
gh search repos "react AND typescript"
gh search repos "bug NOT wontfix"

Wildcards

Limited wildcard support:

# ✅ Wildcards work in some contexts
gh search code "function*" --language=typescript
gh search repos "react-*" in:name

# ❌ Wildcards don't work everywhere
gh search repos "created:>2024-*"  # Doesn't work with dates

JSON Output Quirks

jq is required for field extraction

# ✅ Correct - use jq to extract fields
gh api repos/owner/repo/contents/file.ts | jq -r '.content'

# ❌ Wrong - raw output is base64 + JSON
gh api repos/owner/repo/contents/file.ts

Array handling

# ✅ Correct - iterate array
gh search repos "topic:rust" --json name --jq '.[].name'

# ❌ Wrong - returns raw JSON array
gh search repos "topic:rust" --json name

Null handling

# ✅ Correct - handle nulls
gh api repos/owner/repo/contents/path | jq -r '.content // empty'

# ❌ Wrong - errors on null
gh api repos/owner/repo/contents/path | jq -r '.content'

API Endpoint Quirks

Base64 encoding

File contents from the API are base64-encoded:

# ✅ Correct - decode with base64 -d
gh api repos/owner/repo/contents/file.ts | jq -r '.content' | base64 -d

# ❌ Wrong - outputs base64 gibberish
gh api repos/owner/repo/contents/file.ts | jq -r '.content'

Recursive tree flag

For recursive directory listings, use query parameter:

# ✅ Correct
gh api repos/owner/repo/git/trees/main?recursive=1

# ❌ Wrong - returns only top level
gh api repos/owner/repo/git/trees/main

Ref parameter

Specify branch/tag/commit with ref:

# ✅ Correct
gh api repos/owner/repo/contents/file.ts?ref=dev
gh api repos/owner/repo/contents/file.ts?ref=v1.0.0
gh api repos/owner/repo/contents/file.ts?ref=abc123

# ❌ Wrong - uses default branch
gh api repos/owner/repo/contents/file.ts

Pagination

Default limits

Different commands have different default limits:

# gh search commands default to 30 results
gh search repos "topic:rust"  # Returns max 30

# Specify limit explicitly
gh search repos "topic:rust" --limit 100  # Max 100

# API commands may paginate automatically
gh api repos/owner/repo/issues  # May return all or paginate

Manual pagination

# Use --paginate for API calls
gh api --paginate repos/owner/repo/issues

# Search commands have hard limit of 1000 total results
gh search repos "topic:python" --limit 1000

Permission Errors

Authentication required

Some operations require authentication:

# Works without auth
gh search repos "topic:rust"
gh api repos/owner/repo/contents/README.md

# Requires auth
gh repo view owner/private-repo
gh search repos "is:private"

# Set token
export GH_TOKEN="your_token"
# or
gh auth login

Rate limiting

# Check rate limit status
gh api rate_limit

# Authenticated requests have higher limits
# Unauthenticated: 60 requests/hour
# Authenticated: 5000 requests/hour

Quoting Rules

Shell quoting

# ✅ Double quotes for variables
gh api repos/$OWNER/$REPO/contents/file.ts

# ✅ Single quotes for literal strings
gh search code 'function*'

# ✅ Escape special chars in double quotes
gh search repos "name with \"quotes\""

JSON quoting in --json

# ✅ Comma-separated field list
gh repo view owner/repo --json name,description,stargazerCount

# ❌ Wrong - no quotes around field names
gh repo view owner/repo --json "name","description"

# ❌ Wrong - spaces
gh repo view owner/repo --json name, description

Command-Specific Quirks

gh search vs gh api

Different approaches for different use cases:

# Use gh search for discovery
gh search repos "topic:rust" --sort stars

# Use gh api for precise data
gh api repos/owner/repo --jq '.stargazers_count'

gh repo view vs gh api

Field names differ:

# gh repo view uses camelCase
gh repo view owner/repo --json stargazerCount

# gh api uses snake_case
gh api repos/owner/repo --jq '.stargazers_count'

Common Errors

"No field named X"

You used the wrong field name for the command:

# Error: "No field named stargazersCount"
gh repo view owner/repo --json stargazersCount

# Fix: use stargazerCount for gh repo view
gh repo view owner/repo --json stargazerCount

"Not Found (404)"

File doesn't exist or wrong ref:

# Check file exists in branch
gh api repos/owner/repo/contents/path/file.ts?ref=main

# Try different ref
gh api repos/owner/repo/contents/path/file.ts?ref=dev

"Bad credentials"

Authentication issue:

# Check auth status
gh auth status

# Re-authenticate
gh auth login

Tips

Always test field names

Before using in scripts, test the field name:

# Check available fields
gh repo view owner/repo --json | jq keys

# Check search result fields
gh search repos "query" --json | jq '.[0] | keys'

Use --help

Every command has detailed help:

gh search repos --help
gh api --help
gh repo view --help

Check the manual

For edge cases, check official docs:

CLI manual: https://cli.github.com/manual/
Search syntax: https://docs.github.com/en/search-github
API reference: https://docs.github.com/en/rest

8.9 KiB Raw Blame History