# Gh-Cli - Actions

**Pages:** 15

---

## gh workflow run

**URL:** https://cli.github.com/manual/gh_workflow_run

**Contents:**
- gh workflow run
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Create a workflow_dispatch event for a given workflow.

This command will trigger GitHub Actions to run a given workflow file. The given workflow file must support an on.workflow_dispatch trigger in order to be run in this way.

If the workflow file supports inputs, they can be specified in a few ways:

**Examples:**

Example 1 (unknown):
```unknown
gh workflow run [<workflow-id> | <workflow-name>] [flags]
```

Example 2 (bash):
```bash
# Have gh prompt you for what workflow you'd like to run and interactively collect inputs
$ gh workflow run

# Run the workflow file 'triage.yml' at the remote's default branch
$ gh workflow run triage.yml

# Run the workflow file 'triage.yml' at a specified ref
$ gh workflow run triage.yml --ref my-branch

# Run the workflow file 'triage.yml' with command line inputs
$ gh workflow run triage.yml -f name=scully -f greeting=hello

# Run the workflow file 'triage.yml' with JSON via standard input
$ echo '{"name":"scully", "greeting":"hello"}' | gh workflow run triage.yml --json
```

---

## gh run view

**URL:** https://cli.github.com/manual/gh_run_view

**Contents:**
- gh run view
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - Examples
  - See also

View a summary of a workflow run.

Due to platform limitations, gh may not always be able to associate jobs with their corresponding logs when using the primary method of fetching logs in zip format.

In such cases, gh will attempt to fetch logs for each job individually via the API. This fallback is slower and more resource-intensive. If more than 25 job logs are missing, the operation will fail with an error.

Additionally, due to similar platform constraints, some log lines may not be associated with a specific step within a job. In these cases, the step name will appear as UNKNOWN STEP in the log output.

attempt, conclusion, createdAt, databaseId, displayTitle, event, headBranch, headSha, jobs, name, number, startedAt, status, updatedAt, url, workflowDatabaseId, workflowName

**Examples:**

Example 1 (unknown):
```unknown
gh run view [<run-id>] [flags]
```

Example 2 (bash):
```bash
# Interactively select a run to view, optionally selecting a single job
$ gh run view

# View a specific run
$ gh run view 12345

# View a specific run with specific attempt number
$ gh run view 12345 --attempt 3

# View a specific job within a run
$ gh run view --job 456789

# View the full log for a specific job
$ gh run view --log --job 456789

# Exit non-zero if a run failed
$ gh run view 0451 --exit-status && echo "run pending or passed"
```

---

## gh workflow enable

**URL:** https://cli.github.com/manual/gh_workflow_enable

**Contents:**
- gh workflow enable
  - Options inherited from parent commands
  - See also

Enable a workflow, allowing it to be run and show up when listing workflows.

**Examples:**

Example 1 (unknown):
```unknown
gh workflow enable [<workflow-id> | <workflow-name>]
```

---

## gh workflow

**URL:** https://cli.github.com/manual/gh_workflow

**Contents:**
- gh workflow
  - Available commands
  - Options
  - See also

List, view, and run workflows in GitHub Actions.

---

## gh run

**URL:** https://cli.github.com/manual/gh_run

**Contents:**
- gh run
  - Available commands
  - Options
  - See also

List, view, and watch recent workflow runs from GitHub Actions.

---

## gh run rerun

**URL:** https://cli.github.com/manual/gh_run_rerun

**Contents:**
- gh run rerun
  - Options
  - Options inherited from parent commands
  - See also

Rerun an entire run, only failed jobs, or a specific job from a run.

Note that due to historical reasons, the --job flag may not take what you expect. Specifically, when navigating to a job in the browser, the URL looks like this: https://github.com/<owner>/<repo>/actions/runs/<run-id>/jobs/<number>.

However, this <number> should not be used with the --job flag and will result in the API returning 404 NOT FOUND. Instead, you can get the correct job IDs using the following command:

You will need to use databaseId field for triggering job re-runs.

**Examples:**

Example 1 (unknown):
```unknown
gh run rerun [<run-id>] [flags]
```

Example 2 (unknown):
```unknown
gh run view <run-id> --json jobs --jq '.jobs[] | {name, databaseId}'
```

---

## gh run watch

**URL:** https://cli.github.com/manual/gh_run_watch

**Contents:**
- gh run watch
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Watch a run until it completes, showing its progress.

By default, all steps are displayed. The --compact option can be used to only show the relevant/failed steps.

This command does not support authenticating via fine grained PATs as it is not currently possible to create a PAT with the checks:read permission.

**Examples:**

Example 1 (unknown):
```unknown
gh run watch <run-id> [flags]
```

Example 2 (bash):
```bash
# Watch a run until it's done
$ gh run watch

# Watch a run in compact mode
$ gh run watch --compact

# Run some other command when the run is finished
$ gh run watch && notify-send 'run is done!'
```

---

## gh workflow list

**URL:** https://cli.github.com/manual/gh_workflow_list

**Contents:**
- gh workflow list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List workflow files, hiding disabled workflows by default.

id, name, path, state

**Examples:**

Example 1 (unknown):
```unknown
gh workflow list [flags]
```

---

## gh run list

**URL:** https://cli.github.com/manual/gh_run_list

**Contents:**
- gh run list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List recent workflow runs.

Note that providing the workflow_name to the -w flag will not fetch disabled workflows. Also pass the -a flag to fetch disabled workflow runs using the workflow_name and the -w flag.

Runs created by organization and enterprise ruleset workflows will not display a workflow name due to GitHub API limitations.

attempt, conclusion, createdAt, databaseId, displayTitle, event, headBranch, headSha, name, number, startedAt, status, updatedAt, url, workflowDatabaseId, workflowName

**Examples:**

Example 1 (unknown):
```unknown
gh run list [flags]
```

---

## gh run download

**URL:** https://cli.github.com/manual/gh_run_download

**Contents:**
- gh run download
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Download artifacts generated by a GitHub Actions workflow run.

The contents of each artifact will be extracted under separate directories based on the artifact name. If only a single artifact is specified, it will be extracted into the current directory.

By default, this command downloads the latest artifact created and uploaded through GitHub Actions. Because workflows can delete or overwrite artifacts, <run-id> must be used to select an artifact from a specific workflow run.

**Examples:**

Example 1 (unknown):
```unknown
gh run download [<run-id>] [flags]
```

Example 2 (bash):
```bash
# Download all artifacts generated by a workflow run
$ gh run download <run-id>

# Download a specific artifact within a run
$ gh run download <run-id> -n <name>

# Download specific artifacts across all runs in a repository
$ gh run download -n <name1> -n <name2>

# Select artifacts to download interactively
$ gh run download
```

---

## gh workflow disable

**URL:** https://cli.github.com/manual/gh_workflow_disable

**Contents:**
- gh workflow disable
  - Options inherited from parent commands
  - See also

Disable a workflow, preventing it from running or showing up when listing workflows.

**Examples:**

Example 1 (unknown):
```unknown
gh workflow disable [<workflow-id> | <workflow-name>]
```

---

## gh run cancel

**URL:** https://cli.github.com/manual/gh_run_cancel

**Contents:**
- gh run cancel
  - Options
  - Options inherited from parent commands
  - See also

Cancel a workflow run

**Examples:**

Example 1 (unknown):
```unknown
gh run cancel [<run-id>] [flags]
```

---

## gh run delete

**URL:** https://cli.github.com/manual/gh_run_delete

**Contents:**
- gh run delete
  - Options inherited from parent commands
  - Examples
  - See also

Delete a workflow run

**Examples:**

Example 1 (unknown):
```unknown
gh run delete [<run-id>]
```

Example 2 (bash):
```bash
# Interactively select a run to delete
$ gh run delete

# Delete a specific run
$ gh run delete 12345
```

---

## gh workflow view

**URL:** https://cli.github.com/manual/gh_workflow_view

**Contents:**
- gh workflow view
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

View the summary of a workflow

**Examples:**

Example 1 (unknown):
```unknown
gh workflow view [<workflow-id> | <workflow-name> | <filename>] [flags]
```

Example 2 (bash):
```bash
# Interactively select a workflow to view
$ gh workflow view

# View a specific workflow
$ gh workflow view 0451
```

---

## gh attestation verify

**URL:** https://cli.github.com/manual/gh_attestation_verify

**Contents:**
- gh attestation verify
- Understanding Verification
- Loading Artifacts And Attestations
- Additional Policy Enforcement
  - Options
  - Examples
  - See also

Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations.

An attestation is a claim (i.e. a provenance statement) made by an actor (i.e. a GitHub Actions workflow) regarding a subject (i.e. an artifact).

In order to verify an attestation, you must provide an artifact and validate:

By default, this command enforces the https://slsa.dev/provenance/v1 predicate type. To verify other attestation predicate types use the --predicate-type flag.

The "actor identity" consists of:

This identity is then validated against the attestation's certificate's SourceRepository, SourceRepositoryOwner, and SubjectAlternativeName (SAN) fields, among others.

It is up to you to decide how precisely you want to enforce this identity.

At a minimum, this command requires either:

The more precisely you specify the identity, the more control you will have over the security guarantees offered by the verification process.

Ideally, the path of the signer workflow is also validated using the --signer-workflow or --cert-identity flags.

Please note: if your attestation was generated via a reusable workflow then that reusable workflow is the signer whose identity needs to be validated. In this situation, you must use either the --signer-workflow or the --signer-repo flag.

For more options, see the other available flags.

To specify the artifact, this command requires:

By default, this command will attempt to fetch relevant attestations via the GitHub API using the values provided to --owner or --repo.

To instead fetch attestations from your artifact's OCI registry, use the --bundle-from-oci flag.

For offline verification using attestations stored on disk (c.f. the download command) provide a path to the --bundle flag.

Given the --format=json flag, upon successful verification this command will output a JSON array containing one entry per verified attestation.

This output can then be used for additional policy enforcement, i.e. by being piped into a policy engine.

Each object in the array contains two properties:

Within the verificationResult object you will find:

IMPORTANT: please note that only the signature.certificate and the verifiedTimestamps properties contain values that cannot be manipulated by the workflow that originated the attestation.

When dealing with attestations created within GitHub Actions, the contents of signature.certificate are populated directly from the OpenID Connect token that GitHub has generated. The contents of the verifiedTimestamps array are populated from the signed timestamps originating from either a transparency log or a timestamp authority – and likewise cannot be forged by users.

When designing policy enforcement using this output, special care must be taken when examining the contents of the statement.predicate property: should an attacker gain access to your workflow's execution context, they could then falsify the contents of the statement.predicate.

To mitigate this attack vector, consider using a "trusted builder": when generating an artifact, have the build and attestation signing occur within a reusable workflow whose execution cannot be influenced by input provided through the caller workflow.

See above re: --signer-workflow.

**Examples:**

Example 1 (unknown):
```unknown
gh attestation verify [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]
```

Example 2 (bash):
```bash
# Verify an artifact linked with a repository
$ gh attestation verify example.bin --repo github/example

# Verify an artifact linked with an organization
$ gh attestation verify example.bin --owner github

# Verify an artifact and output the full verification result
$ gh attestation verify example.bin --owner github --format json

# Verify an OCI image using attestations stored on disk
$ gh attestation verify oci://<image-uri> --owner github --bundle sha256:foo.jsonl

# Verify an artifact signed with a reusable workflow
$ gh attestation verify example.bin --owner github --signer-repo actions/example
```

---

# Compare Two Codebases

Systematic workflow for comparing repositories to identify similarities, differences, and unique features.

## When to Use

- "Are repo-a and repo-b providing the same functionality?"
- "What's different between these two implementations?"
- "Which repo has more features?"
- "Can I replace library X with library Y?"

## 4-Step Comparison Workflow

### Step 1: Fetch directory structures

```bash
gh api repos/OWNER-A/REPO-A/contents/PATH > repo1.json
gh api repos/OWNER-B/REPO-B/contents/PATH > repo2.json
```

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

### Step 2: Compare file lists

```bash
jq -r '.[].name' repo1.json > repo1-files.txt
jq -r '.[].name' repo2.json > repo2-files.txt
diff repo1-files.txt repo2-files.txt
```

This shows:
- Files unique to repo1 (prefixed with `<`)
- Files unique to repo2 (prefixed with `>`)
- Common files (no prefix)

### Step 3: Fetch key files for comparison

Compare the most important files:

#### Package dependencies

```bash
gh api repos/OWNER-A/REPO-A/contents/package.json | jq -r '.content' | base64 -d > repo1-pkg.json
gh api repos/OWNER-B/REPO-B/contents/package.json | jq -r '.content' | base64 -d > repo2-pkg.json
```

Then compare dependencies:

```bash
jq '.dependencies' repo1-pkg.json
jq '.dependencies' repo2-pkg.json
```

#### Main entry points

```bash
gh api repos/OWNER-A/REPO-A/contents/src/index.ts | jq -r '.content' | base64 -d > repo1-index.ts
gh api repos/OWNER-B/REPO-B/contents/src/index.ts | jq -r '.content' | base64 -d > repo2-index.ts
```

### Step 4: Analyze differences

Compare the fetched files to identify:

**API Surface**
- What functions/classes are exported?
- Are the APIs similar or completely different?
- Which repo has more comprehensive exports?

**Dependencies**
- Shared dependencies (same approach)
- Different dependencies (different implementation)
- Dependency versions (maintenance status)

**Unique Features**
- Features only in repo1
- Features only in repo2
- Similar features with different implementations

## Example: Compare Solana IDL Libraries

```bash
# Repo 1: solana-fm/explorer-kit (monorepo package)
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls > repo1.json

# Repo 2: tenequm/solana-idls (standalone)
gh api repos/tenequm/solana-idls/contents/ > repo2.json

# Compare file structures
jq -r '.[].name' repo1.json > repo1-files.txt
jq -r '.[].name' repo2.json > repo2-files.txt
diff repo1-files.txt repo2-files.txt

# Fetch package.json from both
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls/package.json | jq -r '.content' | base64 -d > repo1-pkg.json
gh api repos/tenequm/solana-idls/contents/package.json | jq -r '.content' | base64 -d > repo2-pkg.json

# Compare dependencies
echo "=== Repo 1 Dependencies ==="
jq '.dependencies' repo1-pkg.json
echo "=== Repo 2 Dependencies ==="
jq '.dependencies' repo2-pkg.json

# Fetch main entry points
gh api repos/solana-fm/explorer-kit/contents/packages/explorerkit-idls/src/index.ts | jq -r '.content' | base64 -d > repo1-index.ts
gh api repos/tenequm/solana-idls/contents/src/index.ts | jq -r '.content' | base64 -d > repo2-index.ts

# Compare exports
echo "=== Repo 1 Exports ==="
grep -E "^export" repo1-index.ts
echo "=== Repo 2 Exports ==="
grep -E "^export" repo2-index.ts
```

## Analysis Framework

After fetching files, analyze systematically:

### 1. Purpose & Scope
- What problem does each repo solve?
- Same problem or different use cases?

### 2. API Design
- Are the APIs compatible?
- Which is more user-friendly?
- Breaking changes if switching?

### 3. Dependencies
- Shared ecosystem (similar approach)
- Different dependencies (different implementation)
- Heavy vs lightweight

### 4. Maintenance
- Last commit dates
- Release frequency
- Issue/PR activity

### 5. Features
- Core features both have
- Unique to repo1
- Unique to repo2

## Tips

**Compare READMEs first**

```bash
gh api repos/OWNER-A/REPO-A/contents/README.md | jq -r '.content' | base64 -d > repo1-readme.md
gh api repos/OWNER-B/REPO-B/contents/README.md | jq -r '.content' | base64 -d > repo2-readme.md
```

This gives you a high-level understanding before diving into code.

**Check for common file patterns**

- `package.json` - Dependencies and metadata
- `tsconfig.json` - TypeScript configuration
- `src/index.ts` - Main entry point
- `README.md` - Documentation and examples
- `CHANGELOG.md` - Version history

**Use git tree for overview**

```bash
gh api repos/OWNER/REPO/git/trees/main?recursive=1 | jq '.tree[] | select(.type == "blob") | .path' | grep -E "\.(ts|js|json)$"
```

Gets all TypeScript/JavaScript/JSON files quickly.

# Discovering Trending Content

Complete guide to finding popular repositories, code patterns, and active projects on GitHub.

## Find Trending Repositories

### By popularity

```bash
# Most starred repositories (all time)
gh search repos --sort stars --order desc --limit 20

# Most forked repos
gh search repos --sort forks --order desc

# Most help-wanted issues (NOT a watchers sort - there is none)
gh search repos --sort help-wanted-issues --order desc
```

`gh search repos --sort` accepts only `{forks|help-wanted-issues|stars|updated}`. Watcher counts are available per-repo via `gh repo view OWNER/REPO --json watchers`, but you cannot sort search results by them.

### By language

```bash
# Trending repos in specific language
gh search repos --language=rust --sort stars --order desc
gh search repos --language=typescript --sort stars --order desc
gh search repos --language=python --sort stars --order desc
```

### By recency

```bash
# Recently popular (created in last month, sorted by stars)
gh search repos "created:>2024-10-01" --sort stars --order desc

# Created this year
gh search repos "created:>2024-01-01" --sort stars --order desc

# Recently updated popular repos
gh search repos "stars:>100 pushed:>2024-10-01" --sort updated --order desc
```

### By topic

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

# Multiple topics (AND)
gh search repos "topic:blockchain topic:typescript" --sort stars --order desc
```

### By activity

```bash
# Most active repos (by recent updates)
gh search repos --sort updated --order desc

# Active repos (many recent commits)
gh search repos "pushed:>2024-10-01" --sort stars

# Repos with many open issues (active community)
gh search repos "good-first-issues:>5" --sort stars --order desc
```

## Advanced Discovery Queries

### Unique projects

```bash
# Repos with many stars but few forks (unique ideas)
gh search repos "stars:>1000 forks:<100"

# High star-to-fork ratio (original content)
gh search repos "stars:>500 forks:<50"
```

### By file presence

Use `--filename`, `--extension`, and `--match` to scope. Code search has no sorting flags. (The `--filename` flag and an in-query `filename:` qualifier are equivalent - `gh` translates the flag into the qualifier - so either form works.)

```bash
# Find repos by file presence (e.g., has Dockerfile)
gh search code --filename Dockerfile

# Has specific config files
gh search code --filename vite.config.ts
gh search code --filename wxt.config.ts

# Restrict matching to the file path vs file contents
gh search code react --match path --extension tsx
```

### By description keywords

```bash
# Combined filters: Popular Solana repos updated recently
gh search repos "solana in:name,description stars:>100" --sort updated --order desc

# Specific keywords in description
gh search repos "machine learning in:description stars:>1000"
```

### By size and license

```bash
# Small but popular repos (easy to learn from)
gh search repos "stars:>1000 size:<1000" --language=typescript

# Specific license
gh search repos "license:mit stars:>500" --language=rust
```

### By organization

```bash
# Popular repos from specific org
gh search repos "org:vercel stars:>100"
gh search repos "org:anthropics"
```

## Discover Popular Code Patterns

### Find implementations

```bash
# Find implementations (code search has no sorting - scope with --language/--owner/--repo)
gh search code "function useWallet" --language=typescript
gh search code "async fn main" --language=rust

# Specific patterns
gh search code "createContext" --language=typescript
gh search code "impl Display for" --language=rust
```

### By repository

Code search cannot sort by stars, and a `stars:>N` qualifier in the query is matched as literal file text, not a popularity filter. To find code in known-popular repos, first discover the repos with `gh search repos`, then scope code search to them with `--owner`/`--repo`.

```bash
# Scope code search to a specific owner or repo
gh search code "authentication" --language=typescript --owner=vercel
gh search code "middleware" --repo=honojs/hono

# Two-step: find popular repos, then search their code
gh search repos "topic:web-framework stars:>1000" --json fullName --jq '.[].fullName'
gh search code "middleware" --repo=<one-of-the-above>
```

### By organization

```bash
# Search specific organization's popular code
gh search code "authentication" --owner=anthropics
gh search code "config" --owner=vercel
```

### By recency

**Code search has no date filter.** `created:` is not a code-search qualifier - it is matched as literal file text, so `gh search code "React hooks" "created:>2024-01-01"` returns files that literally contain that string (this very page has been a top hit for it). To find recent code, discover recently-pushed repos first, then scope code search to them:

```bash
# 1. Find recently active repos
gh search repos "topic:react pushed:>2026-06-01" --json fullName --jq '.[].fullName'

# 2. Search code within one
gh search code "useEffect" --repo=<one-of-the-above>
```

## Combining Filters

### Examples of powerful combinations

```bash
# Popular TypeScript repos updated this month
gh search repos "language:typescript stars:>500 pushed:>2024-10-01" --sort updated

# New promising projects (recent, growing fast)
gh search repos "created:>2024-06-01 stars:>100" --sort stars --order desc

# Active open-source with good first issues
gh search repos "good-first-issues:>3 stars:>100 pushed:>2024-10-01"

# Well-maintained projects (recent activity + documentation)
gh search repos "stars:>1000 pushed:>2024-10-01" --language=typescript | grep -i "readme"
```

## Qualifiers Reference

### Date qualifiers

- `created:>YYYY-MM-DD` - Created after date
- `created:<YYYY-MM-DD` - Created before date
- `pushed:>YYYY-MM-DD` - Updated after date
- `pushed:<YYYY-MM-DD` - Updated before date

### Numeric qualifiers

- `stars:>N` - More than N stars
- `stars:N..M` - Between N and M stars
- `forks:>N` - More than N forks
- `size:<N` - Smaller than N KB

### Boolean qualifiers

- `is:public` - Public repos
- `is:private` - Private repos (requires auth)
- `archived:false` - Not archived
- `archived:true` - Archived repos

### Location qualifiers

- `in:name` - Search in repo name
- `in:description` - Search in description
- `in:readme` - Search in README
- `in:name,description` - Search in both

## Tips for Discovery

### Start broad, then filter

```bash
# 1. Find all Solana repos
gh search repos "solana"

# 2. Filter by popularity
gh search repos "solana stars:>100"

# 3. Filter by recency
gh search repos "solana stars:>100 pushed:>2024-10-01"

# 4. Add language
gh search repos "solana stars:>100 pushed:>2024-10-01" --language=rust
```

### Use topics for precision

Topics are more precise than text search:

```bash
# Better: Use topic
gh search repos "topic:web3" --sort stars

# Less precise: Text search
gh search repos "web3" --sort stars
```

### Check activity indicators

High stars but old updates = abandoned:

```bash
# Good: Popular AND recently updated
gh search repos "stars:>1000 pushed:>2024-10-01"

# Risk: Popular but potentially stale
gh search repos "stars:>1000"
```

### Look for hidden gems

Sometimes the best code isn't the most popular:

```bash
# Well-maintained but not famous
gh search repos "stars:10..100 pushed:>2024-10-01" --language=rust

# Recent projects gaining traction
gh search repos "created:>2024-09-01 stars:>10" --sort stars
```

## Output formatting

### Get specific fields

```bash
# Just repo names
gh search repos "topic:react" --json name --jq '.[].name'

# Name and star count
gh search repos "topic:react" --limit 5 --json name,stargazersCount --jq '.[] | "\(.name): \(.stargazersCount) stars"'

# Full URLs
gh search repos "topic:rust" --json url --jq '.[].url'
```

### Limit results

```bash
# Top 10 only
gh search repos "language:typescript" --sort stars --limit 10

# Top 50
gh search repos "topic:machine-learning" --limit 50
```

## Common Discovery Workflows

### "Find similar repos to X"

```bash
# 1. Check topics of repo X
gh repo view OWNER/REPO --json repositoryTopics

# 2. Search by those topics
gh search repos "topic:web3 topic:solana" --sort stars --order desc
```

### "What's trending in [language] this month?"

```bash
gh search repos "language:rust created:>2024-10-01" --sort stars --order desc --limit 20
```

### "Find actively maintained [topic] projects"

```bash
gh search repos "topic:blockchain pushed:>2024-10-01 stars:>50" --sort updated --order desc
```

### "Discover new tools for [task]"

```bash
# Example: PDF processing tools
gh search repos "pdf in:name,description language:python stars:>50" --sort stars
```

# Gh-Cli - Extensions

**Pages:** 4

---

## gh extension upgrade

**URL:** https://cli.github.com/manual/gh_extension_upgrade

**Contents:**
- gh extension upgrade
  - Options
  - See also

Upgrade installed extensions

**Examples:**

Example 1 (unknown):
```unknown
gh extension upgrade {<name> | --all} [flags]
```

---

## gh extension browse

**URL:** https://cli.github.com/manual/gh_extension_browse

**Contents:**
- gh extension browse
  - Options
  - See also

This command will take over your terminal and run a fully interactive interface for browsing, adding, and removing gh extensions. A terminal width greater than 100 columns is recommended.

To learn how to control this interface, press ? after running to see the help text.

Running this command with --single-column should make this command more intelligible for users who rely on assistive technology like screen readers or high zoom.

For a more traditional way to discover extensions, see:

along with gh ext install, gh ext remove, and gh repo view.

**Examples:**

Example 1 (unknown):
```unknown
gh extension browse [flags]
```

Example 2 (unknown):
```unknown
gh ext search
```

---

## gh extension list

**URL:** https://cli.github.com/manual/gh_extension_list

**Contents:**
- gh extension list
  - ALIASES
  - See also

List installed extension commands

gh extension ls, gh extensions ls, gh ext ls

**Examples:**

Example 1 (unknown):
```unknown
gh extension list
```

---

## gh extension remove

**URL:** https://cli.github.com/manual/gh_extension_remove

**Contents:**
- gh extension remove
  - See also

Remove an installed extension

**Examples:**

Example 1 (unknown):
```unknown
gh extension remove <name>
```

---

# Gh-Cli - Getting Started

**Pages:** 1

---

## gh auth setup-git

**URL:** https://cli.github.com/manual/gh_auth_setup-git

**Contents:**
- gh auth setup-git
  - Options
  - Examples
  - See also

This command configures git to use GitHub CLI as a credential helper. For more information on git credential helpers please reference: https://git-scm.com/docs/gitcredentials.

By default, GitHub CLI will be set as the credential helper for all authenticated hosts. If there is no authenticated hosts the command fails with an error.

Alternatively, use the --hostname flag to specify a single host to be configured. If the host is not authenticated with, the command fails with an error.

**Examples:**

Example 1 (unknown):
```unknown
gh auth setup-git [flags]
```

Example 2 (bash):
```bash
# Configure git to use GitHub CLI as the credential helper for all authenticated hosts
$ gh auth setup-git

# Configure git to use GitHub CLI as the credential helper for enterprise.internal host
$ gh auth setup-git --hostname enterprise.internal
```

---

# Gh-Cli - Issues

**Pages:** 15

---

## gh issue lock

**URL:** https://cli.github.com/manual/gh_issue_lock

**Contents:**
- gh issue lock
  - Options
  - Options inherited from parent commands
  - See also

Lock issue conversation

**Examples:**

Example 1 (unknown):
```unknown
gh issue lock {<number> | <url>} [flags]
```

---

## gh issue delete

**URL:** https://cli.github.com/manual/gh_issue_delete

**Contents:**
- gh issue delete
  - Options
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh issue delete {<number> | <url>} [flags]
```

---

## gh label

**URL:** https://cli.github.com/manual/gh_label

**Contents:**
- gh label
  - Available commands
  - Options
  - See also

Work with GitHub labels.

---

## gh issue develop

**URL:** https://cli.github.com/manual/gh_issue_develop

**Contents:**
- gh issue develop
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Manage linked branches for an issue.

When using the --base flag, the new development branch will be created from the specified remote branch. The new branch will be configured as the base branch for pull requests created using gh pr create.

**Examples:**

Example 1 (unknown):
```unknown
gh issue develop {<number> | <url>} [flags]
```

Example 2 (bash):
```bash
# List branches for issue 123
$ gh issue develop --list 123

# List branches for issue 123 in repo cli/cli
$ gh issue develop --list --repo cli/cli 123

# Create a branch for issue 123 based on the my-feature branch
$ gh issue develop 123 --base my-feature

# Create a branch for issue 123 and checkout it out
$ gh issue develop 123 --checkout

# Create a branch in repo monalisa/cli for issue 123 in repo cli/cli
$ gh issue develop 123 --repo cli/cli --branch-repo monalisa/cli
```

---

## gh label edit

**URL:** https://cli.github.com/manual/gh_label_edit

**Contents:**
- gh label edit
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Update a label on GitHub.

A label can be renamed using the --name flag.

The label color needs to be 6 character hex value.

**Examples:**

Example 1 (unknown):
```unknown
gh label edit <name> [flags]
```

Example 2 (bash):
```bash
# Update the color of the bug label
$ gh label edit bug --color FF0000

# Rename and edit the description of the bug label
$ gh label edit bug --name big-bug --description "Bigger than normal bug"
```

---

## gh auth status

**URL:** https://cli.github.com/manual/gh_auth_status

**Contents:**
- gh auth status
  - Options
  - JSON Fields
  - Examples
  - See also

Display active account and authentication state on each known GitHub host.

For each host, the authentication state of each known account is tested and any issues are included in the output. Each host section will indicate the active account, which will be used when targeting that host.

If an account on any host (or only the one given via --hostname) has authentication issues, the command will exit with 1 and output to stderr. Note that when using the --json option, the command will always exit with zero regardless of any authentication issues, unless there is a fatal error.

To change the active account for a host, see gh auth switch.

**Examples:**

Example 1 (unknown):
```unknown
gh auth status [flags]
```

Example 2 (bash):
```bash
# Display authentication status for all accounts on all hosts
$ gh auth status

# Display authentication status for the active account on a specific host
$ gh auth status --active --hostname github.example.com

# Display tokens in plain text
$ gh auth status --show-token

# Format authentication status as JSON
$ gh auth status --json hosts

# Include plain text token in JSON output
$ gh auth status --json hosts --show-token

# Format hosts as a flat JSON array
$ gh auth status --json hosts --jq '.hosts | add'
```

---

## gh issue unlock

**URL:** https://cli.github.com/manual/gh_issue_unlock

**Contents:**
- gh issue unlock
  - Options inherited from parent commands
  - See also

Unlock issue conversation

**Examples:**

Example 1 (unknown):
```unknown
gh issue unlock {<number> | <url>}
```

---

## gh alias set

**URL:** https://cli.github.com/manual/gh_alias_set

**Contents:**
- gh alias set
  - Options
  - Examples
  - See also

Define a word that will expand to a full gh command when invoked.

The expansion may specify additional arguments and flags. If the expansion includes positional placeholders such as $1, extra arguments that follow the alias will be inserted appropriately. Otherwise, extra arguments will be appended to the expanded command.

Use - as expansion argument to read the expansion string from standard input. This is useful to avoid quoting issues when defining expansions.

If the expansion starts with ! or if --shell was given, the expansion is a shell expression that will be evaluated through the sh interpreter when the alias is invoked. This allows for chaining multiple commands via piping and redirection.

**Examples:**

Example 1 (unknown):
```unknown
gh alias set <alias> <expansion> [flags]
```

Example 2 (bash):
```bash
# Note: Command Prompt on Windows requires using double quotes for arguments
$ gh alias set pv 'pr view'
$ gh pv -w 123  #=> gh pr view -w 123

$ gh alias set bugs 'issue list --label=bugs'
$ gh bugs

$ gh alias set homework 'issue list --assignee @me'
$ gh homework

$ gh alias set 'issue mine' 'issue list --mention @me'
$ gh issue mine

$ gh alias set epicsBy 'issue list --author="$1" --label="epic"'
$ gh epicsBy vilmibm  #=> gh issue list --author="vilmibm" --label="epic"

$ gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
$ gh igrep epic foo  #=> gh issue list --label="epic" | grep "foo"
```

---

## gh project item-edit

**URL:** https://cli.github.com/manual/gh_project_item-edit

**Contents:**
- gh project item-edit
  - Options
  - Examples
  - See also

Edit either a draft issue or a project item. Both usages require the ID of the item to edit.

For non-draft issues, the ID of the project is also required, and only a single field value can be updated per invocation.

Remove project item field value using --clear flag.

**Examples:**

Example 1 (unknown):
```unknown
gh project item-edit [flags]
```

Example 2 (bash):
```bash
# Edit an item's text field value
$ gh project item-edit --id <item-id> --field-id <field-id> --project-id <project-id> --text "new text"

# Clear an item's field value
$ gh project item-edit --id <item-id> --field-id <field-id> --project-id <project-id> --clear
```

---

## gh issue status

**URL:** https://cli.github.com/manual/gh_issue_status

**Contents:**
- gh issue status
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also
  - In use

Show status of relevant issues

assignees, author, body, closed, closedAt, closedByPullRequestsReferences, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

**Examples:**

Example 1 (unknown):
```unknown
gh issue status [flags]
```

Example 2 (unknown):
```unknown
# Viewing issues relevant to you
~/Projects/my-project$ gh issue status
Issues assigned to you
  #8509 [Fork] Improve how Desktop handles forks  (epic:fork, meta)

Issues mentioning you
  #8938 [Fork] Add create fork flow entry point at commit warning  (epic:fork)
  #8509 [Fork] Improve how Desktop handles forks  (epic:fork, meta)

Issues opened by you
  #8936 [Fork] Hide PR number badges on branches that have an upstream PR  (epic:fork)
  #6386 Improve no editor detected state on conflicts modal  (enhancement)

~/Projects/my-project$
```

---

## gh issue

**URL:** https://cli.github.com/manual/gh_issue

**Contents:**
- gh issue
  - General commands
  - Targeted commands
  - Options
  - Examples
  - See also

Work with GitHub issues.

**Examples:**

Example 1 (bash):
```bash
$ gh issue list
$ gh issue create --label bug
$ gh issue view 123 --web
```

---

## gh issue view

**URL:** https://cli.github.com/manual/gh_issue_view

**Contents:**
- gh issue view
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also
  - In use
    - In terminal
    - In the browser

Display the title, body, and other information about an issue.

With --web flag, open the issue in a web browser instead.

assignees, author, body, closed, closedAt, closedByPullRequestsReferences, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

By default, we will display items in the terminal.

Quickly open an item in the browser using --web or -w

**Examples:**

Example 1 (unknown):
```unknown
gh issue view {<number> | <url>} [flags]
```

Example 2 (unknown):
```unknown
# Viewing an issue in terminal
~/Projects/my-project$ gh issue view 21
Issue title
opened by user. 0 comments. (label)

  Issue body

View this issue on GitHub: https://github.com/owner/repo/issues/21
~/Projects/my-project$
```

Example 3 (unknown):
```unknown
# Viewing an issue in the browser
~/Projects/my-project$ gh issue view 21 --web
Opening https://github.com/owner/repo/issues/21 in your browser.
~/Projects/my-project$
```

---

## gh issue reopen

**URL:** https://cli.github.com/manual/gh_issue_reopen

**Contents:**
- gh issue reopen
  - Options
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh issue reopen {<number> | <url>} [flags]
```

---

## gh issue comment

**URL:** https://cli.github.com/manual/gh_issue_comment

**Contents:**
- gh issue comment
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Add a comment to a GitHub issue.

Without the body text supplied through flags, the command will interactively prompt for the comment text.

**Examples:**

Example 1 (unknown):
```unknown
gh issue comment {<number> | <url>} [flags]
```

Example 2 (bash):
```bash
$ gh issue comment 12 --body "Hi from GitHub CLI"
```

---

## gh issue close

**URL:** https://cli.github.com/manual/gh_issue_close

**Contents:**
- gh issue close
  - Options
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh issue close {<number> | <url>} [flags]
```

---

# Gh-Cli - Other

**Pages:** 60

---

## gh config get

**URL:** https://cli.github.com/manual/gh_config_get

**Contents:**
- gh config get
  - Options
  - Examples
  - See also

Print the value of a given configuration key

**Examples:**

Example 1 (unknown):
```unknown
gh config get <key> [flags]
```

Example 2 (bash):
```bash
$ gh config get git_protocol
```

---

## gh environment

**URL:** https://cli.github.com/manual/gh_help_environment

**Contents:**
- gh environment
  - See also

GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token that will be used when a command targets either github.com or a subdomain of ghe.com. Setting this avoids being prompted to authenticate and takes precedence over previously stored credentials.

GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an authentication token that will be used when a command targets a GitHub Enterprise Server host.

GH_HOST: specify the GitHub hostname for commands where a hostname has not been provided, or cannot be inferred from the context of a local Git repository. If this host was previously authenticated with, the stored credentials will be used. Otherwise, setting GH_TOKEN or GH_ENTERPRISE_TOKEN is required, depending on the targeted host.

GH_REPO: specify the GitHub repository in the [HOST/]OWNER/REPO format for commands that otherwise operate on a local repository.

GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use for authoring text.

GH_BROWSER, BROWSER (in order of precedence): the web browser to use for opening links.

GH_DEBUG: set to a truthy value to enable verbose output on standard error. Set to api to additionally log details of HTTP traffic.

DEBUG (deprecated): set to 1, true, or yes to enable verbose output on standard error.

GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output to, e.g. less.

GLAMOUR_STYLE: the style to use for rendering Markdown. See https://github.com/charmbracelet/glamour#styles

NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.

CLICOLOR: set to 0 to disable printing ANSI colors in output.

CLICOLOR_FORCE: set to a value other than 0 to keep ANSI colors in output even when the output is piped.

GH_COLOR_LABELS: set to any value to display labels using their RGB hex color codes in terminals that support truecolor.

GH_ACCESSIBLE_COLORS (preview): set to a truthy value to use customizable, 4-bit accessible colors.

GH_FORCE_TTY: set to any value to force terminal-style output even when the output is redirected. When the value is a number, it is interpreted as the number of columns available in the viewport. When the value is a percentage, it will be applied against the number of columns available in the current viewport.

GH_NO_UPDATE_NOTIFIER: set to any value to disable GitHub CLI update notifications. When any command is executed, gh checks for new versions once every 24 hours. If a newer version was found, an upgrade notice is displayed on standard error.

GH_NO_EXTENSION_UPDATE_NOTIFIER: set to any value to disable GitHub CLI extension update notifications. When an extension is executed, gh checks for new versions for the executed extension once every 24 hours. If a newer version was found, an upgrade notice is displayed on standard error.

GH_CONFIG_DIR: the directory where gh will store configuration files. If not specified, the default value will be one of the following paths (in order of precedence):

GH_PROMPT_DISABLED: set to any value to disable interactive prompting in the terminal.

GH_PATH: set the path to the gh executable, useful for when gh can not properly determine its own path such as in the cygwin terminal.

GH_MDWIDTH: default maximum width for markdown render wrapping. The max width of lines wrapped on the terminal will be taken as the lesser of the terminal width, this value, or 120 if not specified. This value is used, for example, with pr view subcommand.

GH_ACCESSIBLE_PROMPTER (preview): set to a truthy value to enable prompts that are more compatible with speech synthesis and braille screen readers.

GH_SPINNER_DISABLED: set to a truthy value to replace the spinner animation with a textual progress indicator.

---

## gh org

**URL:** https://cli.github.com/manual/gh_org

**Contents:**
- gh org
  - General commands
  - Examples
  - See also

Work with GitHub organizations.

**Examples:**

Example 1 (bash):
```bash
$ gh org list
```

---

## gh codespace

**URL:** https://cli.github.com/manual/gh_codespace

**Contents:**
- gh codespace
  - Available commands
  - ALIASES
  - See also

Connect to and manage codespaces

---

## gh gist

**URL:** https://cli.github.com/manual/gh_gist

**Contents:**
- gh gist
  - Available commands
  - See also

Work with GitHub gists.

---

## gh alias list

**URL:** https://cli.github.com/manual/gh_alias_list

**Contents:**
- gh alias list
  - ALIASES
  - See also

This command prints out all of the aliases gh is configured to use.

**Examples:**

Example 1 (unknown):
```unknown
gh alias list
```

---

## gh cache

**URL:** https://cli.github.com/manual/gh_cache

**Contents:**
- gh cache
  - Available commands
  - Options
  - Examples
  - See also

Work with GitHub Actions caches.

**Examples:**

Example 1 (bash):
```bash
$ gh cache list
$ gh cache delete --all
```

---

## gh codespace ports forward

**URL:** https://cli.github.com/manual/gh_codespace_ports_forward

**Contents:**
- gh codespace ports forward
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh codespace ports forward <remote-port>:<local-port>...
```

---

## gh codespace edit

**URL:** https://cli.github.com/manual/gh_codespace_edit

**Contents:**
- gh codespace edit
  - Options
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh codespace edit [flags]
```

---

## gh auth login

**URL:** https://cli.github.com/manual/gh_auth_login

**Contents:**
- gh auth login
  - Options
  - Examples
  - See also

Authenticate with a GitHub host.

The default hostname is github.com. This can be overridden using the --hostname flag.

The default authentication mode is a web-based browser flow. After completion, an authentication token will be stored securely in the system credential store. If a credential store is not found or there is an issue using it gh will fallback to writing the token to a plain text file. See gh auth status for its stored location.

Alternatively, use --with-token to pass in a personal access token (classic) on standard input. The minimum required scopes for the token are: repo, read:org, and gist. Take care when passing a fine-grained personal access token to --with-token as the inherent scoping to certain resources may cause confusing behaviour when interacting with other resources. Favour setting GH_TOKEN for fine-grained personal access token usage.

Alternatively, gh will use the authentication token found in environment variables. This method is most suitable for "headless" use of gh such as in automation. See gh help environment for more info.

To use gh in GitHub Actions, add GH_TOKEN: ${{ github.token }} to env.

The git protocol to use for git operations on this host can be set with --git-protocol, or during the interactive prompting. Although login is for a single account on a host, setting the git protocol will take effect for all users on the host.

Specifying ssh for the git protocol will detect existing SSH keys to upload, prompting to create and upload a new key if one is not found. This can be skipped with --skip-ssh-key flag.

For more information on OAuth scopes, see https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/.

**Examples:**

Example 1 (unknown):
```unknown
gh auth login [flags]
```

Example 2 (bash):
```bash
# Start interactive setup
$ gh auth login

# Open a browser to authenticate and copy one-time OAuth code to clipboard
$ gh auth login --web --clipboard

# Authenticate against github.com by reading the token from a file
$ gh auth login --with-token < mytoken.txt

# Authenticate with specific host
$ gh auth login --hostname enterprise.internal
```

---

## gh attestation trusted-root

**URL:** https://cli.github.com/manual/gh_attestation_trusted-root

**Contents:**
- gh attestation trusted-root
  - Options
  - Examples
  - See also

Output contents for a trusted_root.jsonl file, likely for offline verification.

When using gh attestation verify, if your machine is on the internet, this will happen automatically. But to do offline verification, you need to supply a trusted root file with --custom-trusted-root; this command will help you fetch a trusted_root.jsonl file for that purpose.

You can call this command without any flags to get a trusted root file covering the Sigstore Public Good Instance as well as GitHub's Sigstore instance.

Otherwise you can use --tuf-url to specify the URL of a custom TUF repository mirror, and --tuf-root should be the path to the root.json file that you securely obtained out-of-band.

If you just want to verify the integrity of your local TUF repository, and don't want the contents of a trusted_root.jsonl file, use --verify-only.

**Examples:**

Example 1 (unknown):
```unknown
gh attestation trusted-root [--tuf-url <url> --tuf-root <file-path>] [--verify-only] [flags]
```

Example 2 (bash):
```bash
# Get a trusted_root.jsonl for both Sigstore Public Good and GitHub's instance
$ gh attestation trusted-root
```

---

## gh gist edit

**URL:** https://cli.github.com/manual/gh_gist_edit

**Contents:**
- gh gist edit
  - Options
  - See also

Edit one of your gists

**Examples:**

Example 1 (unknown):
```unknown
gh gist edit {<id> | <url>} [<filename>] [flags]
```

---

## gh config list

**URL:** https://cli.github.com/manual/gh_config_list

**Contents:**
- gh config list
  - Options
  - ALIASES
  - See also

Print a list of configuration keys and values

**Examples:**

Example 1 (unknown):
```unknown
gh config list [flags]
```

---

## gh variable set

**URL:** https://cli.github.com/manual/gh_variable_set

**Contents:**
- gh variable set
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Set a value for a variable on one of the following levels:

Organization variable can optionally be restricted to only be available to specific repositories.

**Examples:**

Example 1 (unknown):
```unknown
gh variable set <variable-name> [flags]
```

Example 2 (bash):
```bash
# Add variable value for the current repository in an interactive prompt
$ gh variable set MYVARIABLE

# Read variable value from an environment variable
$ gh variable set MYVARIABLE --body "$ENV_VALUE"

# Read variable value from a file
$ gh variable set MYVARIABLE < myfile.txt

# Set variable for a deployment environment in the current repository
$ gh variable set MYVARIABLE --env myenvironment

# Set organization-level variable visible to both public and private repositories
$ gh variable set MYVARIABLE --org myOrg --visibility all

# Set organization-level variable visible to specific repositories
$ gh variable set MYVARIABLE --org myOrg --repos repo1,repo2,repo3

# Set multiple variables imported from the ".env" file
$ gh variable set -f .env
```

---

## gh gist view

**URL:** https://cli.github.com/manual/gh_gist_view

**Contents:**
- gh gist view
  - Options
  - See also

View the given gist or select from recent gists.

**Examples:**

Example 1 (unknown):
```unknown
gh gist view [<id> | <url>] [flags]
```

---

## gh alias delete

**URL:** https://cli.github.com/manual/gh_alias_delete

**Contents:**
- gh alias delete
  - Options
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh alias delete {<alias> | --all} [flags]
```

---

## gh alias import

**URL:** https://cli.github.com/manual/gh_alias_import

**Contents:**
- gh alias import
  - Options
  - Examples
  - See also

Import aliases from the contents of a YAML file.

Aliases should be defined as a map in YAML, where the keys represent aliases and the values represent the corresponding expansions. An example file should look like the following:

Use - to read aliases (in YAML format) from standard input.

The output from gh alias list can be used to produce a YAML file containing your aliases, which you can use to import them from one machine to another. Run gh help alias list to learn more.

**Examples:**

Example 1 (unknown):
```unknown
gh alias import [<filename> | -] [flags]
```

Example 2 (unknown):
```unknown
bugs: issue list --label=bug
igrep: '!gh issue list --label="$1" | grep "$2"'
features: |-
    issue list
    --label=enhancement
```

Example 3 (bash):
```bash
# Import aliases from a file
$ gh alias import aliases.yml

# Import aliases from standard input
$ gh alias import -
```

---

## gh codespace cp

**URL:** https://cli.github.com/manual/gh_codespace_cp

**Contents:**
- gh codespace cp
  - Options
  - Examples
  - See also

The cp command copies files between the local and remote file systems.

As with the UNIX cp command, the first argument specifies the source and the last specifies the destination; additional sources may be specified after the first, if the destination is a directory.

The --recursive flag is required if any source is a directory.

A remote: prefix on any file name argument indicates that it refers to the file system of the remote (Codespace) machine. It is resolved relative to the home directory of the remote user.

By default, remote file names are interpreted literally. With the --expand flag, each such argument is treated in the manner of scp, as a Bash expression to be evaluated on the remote machine, subject to expansion of tildes, braces, globs, environment variables, and backticks. For security, do not use this flag with arguments provided by untrusted users; see https://lwn.net/Articles/835962/ for discussion.

By default, the cp command will create a public/private ssh key pair to authenticate with the codespace inside the ~/.ssh directory.

**Examples:**

Example 1 (unknown):
```unknown
gh codespace cp [-e] [-r] [-- [<scp flags>...]] <sources>... <dest>
```

Example 2 (bash):
```bash
$ gh codespace cp -e README.md 'remote:/workspaces/$RepositoryName/'
$ gh codespace cp -e 'remote:~/*.go' ./gofiles/
$ gh codespace cp -e 'remote:/workspaces/myproj/go.{mod,sum}' ./gofiles/
$ gh codespace cp -e -- -F ~/.ssh/codespaces_config 'remote:~/*.go' ./gofiles/
```

---

## gh attestation

**URL:** https://cli.github.com/manual/gh_attestation

**Contents:**
- gh attestation
  - Available commands
  - ALIASES
  - See also

Download and verify artifact attestations.

---

## gh codespace jupyter

**URL:** https://cli.github.com/manual/gh_codespace_jupyter

**Contents:**
- gh codespace jupyter
  - Options
  - See also

Open a codespace in JupyterLab

**Examples:**

Example 1 (unknown):
```unknown
gh codespace jupyter [flags]
```

---

## gh gist rename

**URL:** https://cli.github.com/manual/gh_gist_rename

**Contents:**
- gh gist rename
  - See also

Rename a file in the given gist ID / URL.

**Examples:**

Example 1 (unknown):
```unknown
gh gist rename {<id> | <url>} <old-filename> <new-filename>
```

---

## gh completion

**URL:** https://cli.github.com/manual/gh_completion

**Contents:**
- gh completion
  - bash
  - zsh
  - fish
  - PowerShell
  - Options
  - See also

Generate shell completion scripts for GitHub CLI commands.

When installing GitHub CLI through a package manager, it's possible that no additional shell configuration is necessary to gain completion support. For Homebrew, see https://docs.brew.sh/Shell-Completion

If you need to set up completions manually, follow the instructions below. The exact config file locations might vary based on your system. Make sure to restart your shell before testing whether completions are working.

First, ensure that you install bash-completion using your package manager.

After, add this to your ~/.bash_profile:

Generate a _gh completion script and put it somewhere in your $fpath:

Ensure that the following is present in your ~/.zshrc:

Zsh version 5.7 or later is recommended.

Generate a gh.fish completion script:

Open your profile script with:

Add the line and save the file:

**Examples:**

Example 1 (unknown):
```unknown
gh completion -s <shell>
```

Example 2 (unknown):
```unknown
eval "$(gh completion -s bash)"
```

Example 3 (unknown):
```unknown
gh completion -s zsh > /usr/local/share/zsh/site-functions/_gh
```

Example 4 (unknown):
```unknown
autoload -U compinit
compinit -i
```

---

## gh

**URL:** https://cli.github.com/manual/gh

**Contents:**
- gh
  - Core commands
  - GitHub Actions commands
  - Additional commands
  - Options
  - Examples

Work seamlessly with GitHub from the command line.

**Examples:**

Example 1 (bash):
```bash
$ gh issue create
$ gh repo clone cli/cli
$ gh pr checkout 321
```

---

## gh gpg-key add

**URL:** https://cli.github.com/manual/gh_gpg-key_add

**Contents:**
- gh gpg-key add
  - Options
  - See also

Add a GPG key to your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh gpg-key add [<key-file>] [flags]
```

---

## gh codespace ports visibility

**URL:** https://cli.github.com/manual/gh_codespace_ports_visibility

**Contents:**
- gh codespace ports visibility
  - Options inherited from parent commands
  - Examples
  - See also

Change the visibility of the forwarded port

**Examples:**

Example 1 (unknown):
```unknown
gh codespace ports visibility <port>:{public|private|org}...
```

Example 2 (bash):
```bash
$ gh codespace ports visibility 80:org 3000:private 8000:public
```

---

## gh status

**URL:** https://cli.github.com/manual/gh_status

**Contents:**
- gh status
  - Options
  - Examples
  - See also

The status command prints information about your work on GitHub across all the repositories you're subscribed to, including:

**Examples:**

Example 1 (unknown):
```unknown
gh status [flags]
```

Example 2 (bash):
```bash
$ gh status -e cli/cli -e cli/go-gh # Exclude multiple repositories
$ gh status -o cli # Limit results to a single organization
```

---

## gh gpg-key delete

**URL:** https://cli.github.com/manual/gh_gpg-key_delete

**Contents:**
- gh gpg-key delete
  - Options
  - See also

Delete a GPG key from your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh gpg-key delete <key-id> [flags]
```

---

## gh gpg-key

**URL:** https://cli.github.com/manual/gh_gpg-key

**Contents:**
- gh gpg-key
  - Available commands
  - See also

Manage GPG keys registered with your GitHub account.

---

## gh codespace rebuild

**URL:** https://cli.github.com/manual/gh_codespace_rebuild

**Contents:**
- gh codespace rebuild
  - Options
  - See also

Rebuilding recreates your codespace.

Your code and any current changes will be preserved. Your codespace will be rebuilt using your working directory's dev container. A full rebuild also removes cached Docker images.

**Examples:**

Example 1 (unknown):
```unknown
gh codespace rebuild [flags]
```

---

## gh secret delete

**URL:** https://cli.github.com/manual/gh_secret_delete

**Contents:**
- gh secret delete
  - Options
  - Options inherited from parent commands
  - ALIASES
  - See also

Delete a secret on one of the following levels:

**Examples:**

Example 1 (unknown):
```unknown
gh secret delete <secret-name> [flags]
```

---

## gh config set

**URL:** https://cli.github.com/manual/gh_config_set

**Contents:**
- gh config set
  - Options
  - Examples
  - See also

Update configuration with a value for the given key

**Examples:**

Example 1 (unknown):
```unknown
gh config set <key> <value> [flags]
```

Example 2 (bash):
```bash
$ gh config set editor vim
$ gh config set editor "code --wait"
$ gh config set git_protocol ssh --host github.com
$ gh config set prompt disabled
```

---

## gh gist list

**URL:** https://cli.github.com/manual/gh_gist_list

**Contents:**
- gh gist list
  - Options
  - ALIASES
  - Examples
  - See also

List gists from your user account.

You can use a regular expression to filter the description, file names, or even the content of files in the gist using --filter.

For supported regular expression syntax, see https://pkg.go.dev/regexp/syntax.

Use --include-content to include content of files, noting that this will be slower and increase the rate limit used. Instead of printing a table, code will be printed with highlights similar to gh search code:

No highlights or other color is printed when output is redirected.

**Examples:**

Example 1 (unknown):
```unknown
gh gist list [flags]
```

Example 2 (unknown):
```unknown
{{gist ID}} {{file name}}
    {{description}}
        {{matching lines from content}}
```

Example 3 (bash):
```bash
# List all secret gists from your user account
$ gh gist list --secret

# Find all gists from your user account mentioning "octo" anywhere
$ gh gist list --filter octo --include-content
```

---

## gh variable delete

**URL:** https://cli.github.com/manual/gh_variable_delete

**Contents:**
- gh variable delete
  - Options
  - Options inherited from parent commands
  - ALIASES
  - See also

Delete a variable on one of the following levels:

**Examples:**

Example 1 (unknown):
```unknown
gh variable delete <variable-name> [flags]
```

---

## gh codespace stop

**URL:** https://cli.github.com/manual/gh_codespace_stop

**Contents:**
- gh codespace stop
  - Options
  - See also

Stop a running codespace

**Examples:**

Example 1 (unknown):
```unknown
gh codespace stop [flags]
```

---

## gh auth

**URL:** https://cli.github.com/manual/gh_auth

**Contents:**
- gh auth
  - Available commands
  - See also

Authenticate gh and git with GitHub

---

## gh gist delete

**URL:** https://cli.github.com/manual/gh_gist_delete

**Contents:**
- gh gist delete
  - Options
  - Examples
  - See also

Delete a GitHub gist.

To delete a gist interactively, use gh gist delete with no arguments.

To delete a gist non-interactively, supply the gist id or url.

**Examples:**

Example 1 (unknown):
```unknown
gh gist delete {<id> | <url>} [flags]
```

Example 2 (bash):
```bash
# Delete a gist interactively
$ gh gist delete

# Delete a gist non-interactively
$ gh gist delete 1234
```

---

## gh ssh-key delete

**URL:** https://cli.github.com/manual/gh_ssh-key_delete

**Contents:**
- gh ssh-key delete
  - Options
  - See also

Delete an SSH key from your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh ssh-key delete <id> [flags]
```

---

## gh ssh-key list

**URL:** https://cli.github.com/manual/gh_ssh-key_list

**Contents:**
- gh ssh-key list
  - ALIASES
  - See also

Lists SSH keys in your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh ssh-key list
```

---

## gh codespace code

**URL:** https://cli.github.com/manual/gh_codespace_code

**Contents:**
- gh codespace code
  - Options
  - See also

Open a codespace in Visual Studio Code

**Examples:**

Example 1 (unknown):
```unknown
gh codespace code [flags]
```

---

## gh secret set

**URL:** https://cli.github.com/manual/gh_secret_set

**Contents:**
- gh secret set
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Set a value for a secret on one of the following levels:

Organization and user secrets can optionally be restricted to only be available to specific repositories.

Secret values are locally encrypted before being sent to GitHub.

**Examples:**

Example 1 (unknown):
```unknown
gh secret set <secret-name> [flags]
```

Example 2 (bash):
```bash
# Paste secret value for the current repository in an interactive prompt
$ gh secret set MYSECRET

# Read secret value from an environment variable
$ gh secret set MYSECRET --body "$ENV_VALUE"

# Set secret for a specific remote repository
$ gh secret set MYSECRET --repo origin/repo --body "$ENV_VALUE"

# Read secret value from a file
$ gh secret set MYSECRET < myfile.txt

# Set secret for a deployment environment in the current repository
$ gh secret set MYSECRET --env myenvironment

# Set organization-level secret visible to both public and private repositories
$ gh secret set MYSECRET --org myOrg --visibility all

# Set organization-level secret visible to specific repositories
$ gh secret set MYSECRET --org myOrg --repos repo1,repo2,repo3

# Set organization-level secret visible to no repositories
$ gh secret set MYSECRET --org myOrg --no-repos-selected

# Set user-level secret for Codespaces
$ gh secret set MYSECRET --user

# Set repository-level secret for Dependabot
$ gh secret set MYSECRET --app dependabot

# Set multiple secrets imported from the ".env" file
$ gh secret set -f .env

# Set multiple secrets from stdin
$ gh secret set -f - < myfile.txt
```

---

## gh org list

**URL:** https://cli.github.com/manual/gh_org_list

**Contents:**
- gh org list
  - Options
  - ALIASES
  - Examples
  - See also

List organizations for the authenticated user.

**Examples:**

Example 1 (unknown):
```unknown
gh org list [flags]
```

Example 2 (bash):
```bash
# List the first 30 organizations
$ gh org list

# List more organizations
$ gh org list --limit 100
```

---

## gh secret list

**URL:** https://cli.github.com/manual/gh_secret_list

**Contents:**
- gh secret list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List secrets on one of the following levels:

name, numSelectedRepos, selectedReposURL, updatedAt, visibility

**Examples:**

Example 1 (unknown):
```unknown
gh secret list [flags]
```

---

## gh auth refresh

**URL:** https://cli.github.com/manual/gh_auth_refresh

**Contents:**
- gh auth refresh
  - Options
  - Examples
  - See also

Expand or fix the permission scopes for stored credentials for active account.

The --scopes flag accepts a comma separated list of scopes you want your gh credentials to have. If no scopes are provided, the command maintains previously added scopes.

The --remove-scopes flag accepts a comma separated list of scopes you want to remove from your gh credentials. Scope removal is idempotent. The minimum set of scopes (repo, read:org, and gist) cannot be removed.

The --reset-scopes flag resets the scopes for your gh credentials to the default set of scopes for your auth flow.

If you have multiple accounts in gh auth status and want to refresh the credentials for an inactive account, you will have to use gh auth switch to that account first before using this command, and then switch back when you are done.

For more information on OAuth scopes, see https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/.

**Examples:**

Example 1 (unknown):
```unknown
gh auth refresh [flags]
```

Example 2 (bash):
```bash
# Open a browser to add write:org and read:public_key scopes
$ gh auth refresh --scopes write:org,read:public_key

# Open a browser to ensure your authentication credentials have the correct minimum scopes
$ gh auth refresh

# Open a browser to idempotently remove the delete_repo scope
$ gh auth refresh --remove-scopes delete_repo

# Open a browser to re-authenticate with the default minimum scopes
$ gh auth refresh --reset-scopes

# Open a browser to re-authenticate and copy one-time OAuth code to clipboard
$ gh auth refresh --clipboard
```

---

## gh cache delete

**URL:** https://cli.github.com/manual/gh_cache_delete

**Contents:**
- gh cache delete
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Delete GitHub Actions caches.

Deletion requires authorization with the repo scope.

**Examples:**

Example 1 (unknown):
```unknown
gh cache delete [<cache-id> | <cache-key> | --all] [flags]
```

Example 2 (bash):
```bash
# Delete a cache by id
$ gh cache delete 1234

# Delete a cache by key
$ gh cache delete cache-key

# Delete a cache by id in a specific repo
$ gh cache delete 1234 --repo cli/cli

# Delete a cache by key and branch ref
$ gh cache delete cache-key --ref refs/heads/feature-branch

# Delete a cache by key and PR ref
$ gh cache delete cache-key --ref refs/pull/<PR-number>/merge

# Delete all caches (exit code 1 on no caches)
$ gh cache delete --all

# Delete all caches (exit code 0 on no caches)
$ gh cache delete --all --succeed-on-no-caches
```

---

## gh config clear-cache

**URL:** https://cli.github.com/manual/gh_config_clear-cache

**Contents:**
- gh config clear-cache
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh config clear-cache
```

Example 2 (bash):
```bash
# Clear the cli cache
$ gh config clear-cache
```

---

## gh codespace logs

**URL:** https://cli.github.com/manual/gh_codespace_logs

**Contents:**
- gh codespace logs
  - Options
  - See also

Access codespace logs

**Examples:**

Example 1 (unknown):
```unknown
gh codespace logs [flags]
```

---

## gh alias

**URL:** https://cli.github.com/manual/gh_alias

**Contents:**
- gh alias
  - Available commands
  - See also

Aliases can be used to make shortcuts for gh commands or to compose multiple commands.

Run gh help alias set to learn more.

---

## gh cache list

**URL:** https://cli.github.com/manual/gh_cache_list

**Contents:**
- gh cache list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - Examples
  - See also

List GitHub Actions caches

createdAt, id, key, lastAccessedAt, ref, sizeInBytes, version

**Examples:**

Example 1 (unknown):
```unknown
gh cache list [flags]
```

Example 2 (bash):
```bash
# List caches for current repository
$ gh cache list

# List caches for specific repository
$ gh cache list --repo cli/cli

# List caches sorted by least recently accessed
$ gh cache list --sort last_accessed_at --order asc

# List caches that have keys matching a prefix (or that match exactly)
$ gh cache list --key key-prefix

# List caches for a specific branch, replace <branch-name> with the actual branch name
$ gh cache list --ref refs/heads/<branch-name>

# List caches for a specific pull request, replace <pr-number> with the actual pull request number
$ gh cache list --ref refs/pull/<pr-number>/merge
```

---

## gh codespace ports

**URL:** https://cli.github.com/manual/gh_codespace_ports

**Contents:**
- gh codespace ports
  - Available commands
  - Options
  - JSON Fields
  - See also

List ports in a codespace

browseUrl, label, sourcePort, visibility

**Examples:**

Example 1 (unknown):
```unknown
gh codespace ports [flags]
```

---

## gh auth logout

**URL:** https://cli.github.com/manual/gh_auth_logout

**Contents:**
- gh auth logout
  - Options
  - Examples
  - See also

Remove authentication for a GitHub account.

This command removes the stored authentication configuration for an account. The authentication configuration is only removed locally.

This command does not revoke authentication tokens.

To revoke all authentication tokens generated by the GitHub CLI:

Note: this procedure will revoke all authentication tokens ever generated by the GitHub CLI across all your devices.

For more information about revoking OAuth application tokens, see: https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps

**Examples:**

Example 1 (unknown):
```unknown
gh auth logout [flags]
```

Example 2 (bash):
```bash
# Select what host and account to log out of via a prompt
$ gh auth logout

# Log out of a specific host and specific account
$ gh auth logout --hostname enterprise.internal --user monalisa
```

---

## GitHub CLI manual

**URL:** https://cli.github.com/manual/

**Contents:**
- GitHub CLI manual
- Installation
- Configuration
- GitHub Enterprise
- Support

GitHub CLI, or gh, is a command-line interface to GitHub for use in your terminal or your scripts.

You can find installation instructions on our README.

Run gh auth login to authenticate with your GitHub account. Alternatively, gh will respect the GITHUB_TOKEN environment variable.

To set your preferred editor, use gh config set editor <editor>. Read more about gh config and environment variables.

Declare your aliases for often-used commands with gh alias set.

GitHub CLI supports GitHub Enterprise Server 2.20 and above. To authenticate with a GitHub instance, run:

To define this host as a default for all GitHub CLI commands, set the GH_HOST environment variable:

Finally, to authenticate commands in scripting mode or automation, set the GH_ENTERPRISE_TOKEN:

Ask usage questions and send us feedback in Discussions

Report bugs or search for existing feature requests in our issue tracker

**Examples:**

Example 1 (unknown):
```unknown
gh auth login --hostname <hostname>
```

Example 2 (unknown):
```unknown
export GH_HOST=<hostname>
```

Example 3 (unknown):
```unknown
export GH_ENTERPRISE_TOKEN=<access-token>
```

---

## gh auth token

**URL:** https://cli.github.com/manual/gh_auth_token

**Contents:**
- gh auth token
  - Options
  - See also

This command outputs the authentication token for an account on a given GitHub host.

Without the --hostname flag, the default host is chosen.

Without the --user flag, the active account for the host is chosen.

**Examples:**

Example 1 (unknown):
```unknown
gh auth token [flags]
```

---

## gh agent-task view

**URL:** https://cli.github.com/manual/gh_agent-task_view

**Contents:**
- gh agent-task view
  - Options
  - Examples
  - See also

View an agent task session.

**Examples:**

Example 1 (unknown):
```unknown
gh agent-task view [<session-id> | <pr-number> | <pr-url> | <pr-branch>] [flags]
```

Example 2 (bash):
```bash
# View an agent task by session ID
$ gh agent-task view e2fa49d2-f164-4a56-ab99-498090b8fcdf

# View an agent task by pull request number in current repo
$ gh agent-task view 12345

# View an agent task by pull request number
$ gh agent-task view --repo OWNER/REPO 12345

# View an agent task by pull request reference
$ gh agent-task view OWNER/REPO#12345

# View a pull request agents tasks in the browser
$ gh agent-task view 12345 --web
```

---

## gh ssh-key add

**URL:** https://cli.github.com/manual/gh_ssh-key_add

**Contents:**
- gh ssh-key add
  - Options
  - See also

Add an SSH key to your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh ssh-key add [<key-file>] [flags]
```

---

## gh codespace ssh

**URL:** https://cli.github.com/manual/gh_codespace_ssh

**Contents:**
- gh codespace ssh
  - Options
  - Examples
  - See also

The ssh command is used to SSH into a codespace. In its simplest form, you can run gh cs ssh, select a codespace interactively, and connect.

The ssh command will automatically create a public/private ssh key pair in the ~/.ssh directory if you do not have an existing valid key pair. When selecting the key pair to use, the preferred order is:

The ssh command also supports deeper integration with OpenSSH using a --config option that generates per-codespace ssh configuration in OpenSSH format. Including this configuration in your ~/.ssh/config improves the user experience of tools that integrate with OpenSSH, such as Bash/Zsh completion of ssh hostnames, remote path completion for scp/rsync/sshfs, git ssh remotes, and so on.

Once that is set up (see the second example below), you can ssh to codespaces as if they were ordinary remote hosts (using ssh, not gh cs ssh).

Note that the codespace you are connecting to must have an SSH server pre-installed. If the docker image being used for the codespace does not have an SSH server, install it in your Dockerfile or, for codespaces that use Debian-based images, you can add the following to your devcontainer.json:

**Examples:**

Example 1 (unknown):
```unknown
gh codespace ssh [<flags>...] [-- <ssh-flags>...] [<command>]
```

Example 2 (unknown):
```unknown
"features": {
	"ghcr.io/devcontainers/features/sshd:1": {
		"version": "latest"
	}
}
```

Example 3 (bash):
```bash
$ gh codespace ssh

$ gh codespace ssh --config > ~/.ssh/codespaces
$ printf 'Match all\nInclude ~/.ssh/codespaces\n' >> ~/.ssh/config
```

---

## gh auth switch

**URL:** https://cli.github.com/manual/gh_auth_switch

**Contents:**
- gh auth switch
  - Options
  - Examples
  - See also

Switch the active account for a GitHub host.

This command changes the authentication configuration that will be used when running commands targeting the specified GitHub host.

If the specified host has two accounts, the active account will be switched automatically. If there are more than two accounts, disambiguation will be required either through the --user flag or an interactive prompt.

For a list of authenticated accounts you can run gh auth status.

**Examples:**

Example 1 (unknown):
```unknown
gh auth switch [flags]
```

Example 2 (bash):
```bash
# Select what host and account to switch to via a prompt
$ gh auth switch

# Switch the active account on a specific host to a specific user
$ gh auth switch --hostname enterprise.internal --user monalisa
```

---

## gh config

**URL:** https://cli.github.com/manual/gh_config

**Contents:**
- gh config
  - Available commands
  - See also

Display or change configuration settings for gh.

Current respected settings:

---

## gh ssh-key

**URL:** https://cli.github.com/manual/gh_ssh-key

**Contents:**
- gh ssh-key
  - Available commands
  - See also

Manage SSH keys registered with your GitHub account.

---

## gh gpg-key list

**URL:** https://cli.github.com/manual/gh_gpg-key_list

**Contents:**
- gh gpg-key list
  - ALIASES
  - See also

Lists GPG keys in your GitHub account

**Examples:**

Example 1 (unknown):
```unknown
gh gpg-key list
```

---

## gh browse

**URL:** https://cli.github.com/manual/gh_browse

**Contents:**
- gh browse
  - Options
  - Examples
  - See also

Transition from the terminal to the web browser to view and interact with:

**Examples:**

Example 1 (unknown):
```unknown
gh browse [<number> | <path> | <commit-sha>] [flags]
```

Example 2 (bash):
```bash
# Open the home page of the current repository
$ gh browse

# Open the script directory of the current repository
$ gh browse script/

# Open issue or pull request 217
$ gh browse 217

# Open commit page
$ gh browse 77507cd94ccafcf568f8560cfecde965fcfa63

# Open repository settings
$ gh browse --settings

# Open main.go at line 312
$ gh browse main.go:312

# Open main.go with the repository at head of bug-fix branch
$ gh browse main.go --branch bug-fix

# Open main.go with the repository at commit 775007cd
$ gh browse main.go --commit=77507cd94ccafcf568f8560cfecde965fcfa63
```

---

# Gh-Cli - Pull Requests

**Pages:** 31

---

## gh project view

**URL:** https://cli.github.com/manual/gh_project_view

**Contents:**
- gh project view
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project view [<number>] [flags]
```

Example 2 (bash):
```bash
# View the current user's project "1"
$ gh project view 1

# Open user monalisa's project "1" in the browser
$ gh project view 1 --owner monalisa --web
```

---

## gh pr merge

**URL:** https://cli.github.com/manual/gh_pr_merge

**Contents:**
- gh pr merge
  - Options
  - Options inherited from parent commands
  - See also

Merge a pull request on GitHub.

Without an argument, the pull request that belongs to the current branch is selected.

When targeting a branch that requires a merge queue, no merge strategy is required. If required checks have not yet passed, auto-merge will be enabled. If required checks have passed, the pull request will be added to the merge queue. To bypass a merge queue and merge directly, pass the --admin flag.

**Examples:**

Example 1 (unknown):
```unknown
gh pr merge [<number> | <url> | <branch>] [flags]
```

---

## gh project copy

**URL:** https://cli.github.com/manual/gh_project_copy

**Contents:**
- gh project copy
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project copy [<number>] [flags]
```

Example 2 (bash):
```bash
# Copy project "1" owned by monalisa to github
$ gh project copy 1 --source-owner monalisa --target-owner github --title "a new project"
```

---

## gh project item-add

**URL:** https://cli.github.com/manual/gh_project_item-add

**Contents:**
- gh project item-add
  - Options
  - Examples
  - See also

Add a pull request or an issue to a project

**Examples:**

Example 1 (unknown):
```unknown
gh project item-add [<number>] [flags]
```

Example 2 (bash):
```bash
# Add an item to monalisa's project "1"
$ gh project item-add 1 --owner monalisa --url https://github.com/monalisa/myproject/issues/23
```

---

## gh preview prompter

**URL:** https://cli.github.com/manual/gh_preview_prompter

**Contents:**
- gh preview prompter
  - See also

Execute a test program to preview the prompter. Without an argument, all prompts will be run.

Available prompt types:

**Examples:**

Example 1 (unknown):
```unknown
gh preview prompter [prompt type]
```

---

## gh pr update-branch

**URL:** https://cli.github.com/manual/gh_pr_update-branch

**Contents:**
- gh pr update-branch
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Update a pull request branch with latest changes of the base branch.

Without an argument, the pull request that belongs to the current branch is selected.

The default behavior is to update with a merge commit (i.e., merging the base branch into the PR's branch). To reconcile the changes with rebasing on top of the base branch, the --rebase option should be provided.

**Examples:**

Example 1 (unknown):
```unknown
gh pr update-branch [<number> | <url> | <branch>] [flags]
```

Example 2 (bash):
```bash
$ gh pr update-branch 23
$ gh pr update-branch 23 --rebase
$ gh pr update-branch 23 --repo owner/repo
```

---

## gh agent-task list

**URL:** https://cli.github.com/manual/gh_agent-task_list

**Contents:**
- gh agent-task list
  - Options
  - See also

List agent tasks (preview)

**Examples:**

Example 1 (unknown):
```unknown
gh agent-task list [flags]
```

---

## gh pr edit

**URL:** https://cli.github.com/manual/gh_pr_edit

**Contents:**
- gh pr edit
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Without an argument, the pull request that belongs to the current branch is selected.

Editing a pull request's projects requires authorization with the project scope. To authorize, run gh auth refresh -s project.

The --add-assignee and --remove-assignee flags both support the following special values:

The --add-reviewer and --remove-reviewer flags do not support these special values.

**Examples:**

Example 1 (unknown):
```unknown
gh pr edit [<number> | <url> | <branch>] [flags]
```

Example 2 (bash):
```bash
$ gh pr edit 23 --title "I found a bug" --body "Nothing works"
$ gh pr edit 23 --add-label "bug,help wanted" --remove-label "core"
$ gh pr edit 23 --add-reviewer monalisa,hubot  --remove-reviewer myorg/team-name
$ gh pr edit 23 --add-assignee "@me" --remove-assignee monalisa,hubot
$ gh pr edit 23 --add-assignee "@copilot"
$ gh pr edit 23 --add-project "Roadmap" --remove-project v1,v2
$ gh pr edit 23 --milestone "Version 1"
$ gh pr edit 23 --remove-milestone
```

---

## gh project mark-template

**URL:** https://cli.github.com/manual/gh_project_mark-template

**Contents:**
- gh project mark-template
  - Options
  - Examples
  - See also

Mark a project as a template

**Examples:**

Example 1 (unknown):
```unknown
gh project mark-template [<number>] [flags]
```

Example 2 (bash):
```bash
# Mark the github org's project "1" as a template
$ gh project mark-template 1 --owner "github"

# Unmark the github org's project "1" as a template
$ gh project mark-template 1 --owner "github" --undo
```

---

## gh pr review

**URL:** https://cli.github.com/manual/gh_pr_review

**Contents:**
- gh pr review
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Add a review to a pull request.

Without an argument, the pull request that belongs to the current branch is reviewed.

**Examples:**

Example 1 (unknown):
```unknown
gh pr review [<number> | <url> | <branch>] [flags]
```

Example 2 (bash):
```bash
# Approve the pull request of the current branch
$ gh pr review --approve

# Leave a review comment for the current branch
$ gh pr review --comment -b "interesting"

# Add a review for a specific pull request
$ gh pr review 123

# Request changes on a specific pull request
$ gh pr review 123 -r -b "needs more ASCII art"
```

---

## gh preview

**URL:** https://cli.github.com/manual/gh_preview

**Contents:**
- gh preview
  - Available commands
  - See also

Preview commands are for testing, demonstrative, and development purposes only. They should be considered unstable and can change at any time.

---

## gh pr close

**URL:** https://cli.github.com/manual/gh_pr_close

**Contents:**
- gh pr close
  - Options
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh pr close {<number> | <url> | <branch>} [flags]
```

---

## gh project delete

**URL:** https://cli.github.com/manual/gh_project_delete

**Contents:**
- gh project delete
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project delete [<number>] [flags]
```

Example 2 (bash):
```bash
# Delete the current user's project "1"
$ gh project delete 1 --owner "@me"
```

---

## gh pr lock

**URL:** https://cli.github.com/manual/gh_pr_lock

**Contents:**
- gh pr lock
  - Options
  - Options inherited from parent commands
  - See also

Lock pull request conversation

**Examples:**

Example 1 (unknown):
```unknown
gh pr lock {<number> | <url>} [flags]
```

---

## gh agent-task

**URL:** https://cli.github.com/manual/gh_agent-task

**Contents:**
- gh agent-task
  - Available commands
  - ALIASES
  - Examples
  - See also

Working with agent tasks in the GitHub CLI is in preview and subject to change without notice.

gh agent, gh agents, gh agent-tasks

**Examples:**

Example 1 (unknown):
```unknown
gh agent-task <command>
```

Example 2 (bash):
```bash
# List your most recent agent tasks
$ gh agent-task list

# Create a new agent task on the current repository
$ gh agent-task create "Improve the performance of the data processing pipeline"

# View details about agent tasks associated with a pull request
$ gh agent-task view 123

# View details about a specific agent task
$ gh agent-task view 12345abc-12345-12345-12345-12345abc
```

---

## gh pr comment

**URL:** https://cli.github.com/manual/gh_pr_comment

**Contents:**
- gh pr comment
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Add a comment to a GitHub pull request.

Without the body text supplied through flags, the command will interactively prompt for the comment text.

**Examples:**

Example 1 (unknown):
```unknown
gh pr comment [<number> | <url> | <branch>] [flags]
```

Example 2 (bash):
```bash
$ gh pr comment 13 --body "Hi from GitHub CLI"
```

---

## gh project item-archive

**URL:** https://cli.github.com/manual/gh_project_item-archive

**Contents:**
- gh project item-archive
  - Options
  - Examples
  - See also

Archive an item in a project

**Examples:**

Example 1 (unknown):
```unknown
gh project item-archive [<number>] [flags]
```

Example 2 (bash):
```bash
# Archive an item in the current user's project "1"
$ gh project item-archive 1 --owner "@me" --id <item-ID>
```

---

## gh project item-delete

**URL:** https://cli.github.com/manual/gh_project_item-delete

**Contents:**
- gh project item-delete
  - Options
  - Examples
  - See also

Delete an item from a project by ID

**Examples:**

Example 1 (unknown):
```unknown
gh project item-delete [<number>] [flags]
```

Example 2 (bash):
```bash
# Delete an item in the current user's project "1"
$ gh project item-delete 1 --owner "@me" --id <item-id>
```

---

## gh project close

**URL:** https://cli.github.com/manual/gh_project_close

**Contents:**
- gh project close
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project close [<number>] [flags]
```

Example 2 (bash):
```bash
# Close project "1" owned by monalisa
$ gh project close 1 --owner monalisa

# Reopen closed project "1" owned by github
$ gh project close 1 --owner github --undo
```

---

## gh project field-list

**URL:** https://cli.github.com/manual/gh_project_field-list

**Contents:**
- gh project field-list
  - Options
  - Examples
  - See also

List the fields in a project

**Examples:**

Example 1 (unknown):
```unknown
gh project field-list [<number>] [flags]
```

Example 2 (bash):
```bash
# List fields in the current user's project "1"
$ gh project field-list 1 --owner "@me"
```

---

## gh project edit

**URL:** https://cli.github.com/manual/gh_project_edit

**Contents:**
- gh project edit
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project edit [<number>] [flags]
```

Example 2 (bash):
```bash
# Edit the title of monalisa's project "1"
$ gh project edit 1 --owner monalisa --title "New title"
```

---

## gh project item-list

**URL:** https://cli.github.com/manual/gh_project_item-list

**Contents:**
- gh project item-list
  - Options
  - Examples
  - See also

List the items in a project

**Examples:**

Example 1 (unknown):
```unknown
gh project item-list [<number>] [flags]
```

Example 2 (bash):
```bash
# List the items in the current users's project "1"
$ gh project item-list 1 --owner "@me"
```

---

## gh pr diff

**URL:** https://cli.github.com/manual/gh_pr_diff

**Contents:**
- gh pr diff
  - Options
  - Options inherited from parent commands
  - See also

View changes in a pull request.

Without an argument, the pull request that belongs to the current branch is selected.

With --web flag, open the pull request diff in a web browser instead.

**Examples:**

Example 1 (unknown):
```unknown
gh pr diff [<number> | <url> | <branch>] [flags]
```

---

## gh project list

**URL:** https://cli.github.com/manual/gh_project_list

**Contents:**
- gh project list
  - Options
  - ALIASES
  - Examples
  - See also

List the projects for an owner

**Examples:**

Example 1 (unknown):
```unknown
gh project list [flags]
```

Example 2 (bash):
```bash
# List the current user's projects
$ gh project list

# List the projects for org github including closed projects
$ gh project list --owner github --closed
```

---

## gh project

**URL:** https://cli.github.com/manual/gh_project

**Contents:**
- gh project
  - Available commands
  - Examples
  - See also

Work with GitHub Projects.

The minimum required scope for the token is: project. You can verify your token scope by running gh auth status and add the project scope by running gh auth refresh -s project.

**Examples:**

Example 1 (bash):
```bash
$ gh project create --owner monalisa --title "Roadmap"
$ gh project view 1 --owner cli --web
$ gh project field-list 1 --owner cli
$ gh project item-list 1 --owner cli
```

---

## gh pr unlock

**URL:** https://cli.github.com/manual/gh_pr_unlock

**Contents:**
- gh pr unlock
  - Options inherited from parent commands
  - See also

Unlock pull request conversation

**Examples:**

Example 1 (unknown):
```unknown
gh pr unlock {<number> | <url>}
```

---

## gh pr reopen

**URL:** https://cli.github.com/manual/gh_pr_reopen

**Contents:**
- gh pr reopen
  - Options
  - Options inherited from parent commands
  - See also

Reopen a pull request

**Examples:**

Example 1 (unknown):
```unknown
gh pr reopen {<number> | <url> | <branch>} [flags]
```

---

## gh project field-delete

**URL:** https://cli.github.com/manual/gh_project_field-delete

**Contents:**
- gh project field-delete
  - Options
  - See also

Delete a field in a project

**Examples:**

Example 1 (unknown):
```unknown
gh project field-delete [flags]
```

---

## gh pr

**URL:** https://cli.github.com/manual/gh_pr

**Contents:**
- gh pr
  - General commands
  - Targeted commands
  - Options
  - Examples
  - See also

Work with GitHub pull requests.

**Examples:**

Example 1 (bash):
```bash
$ gh pr checkout 353
$ gh pr create --fill
$ gh pr view --web
```

---

## gh pr checks

**URL:** https://cli.github.com/manual/gh_pr_checks

**Contents:**
- gh pr checks
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also

Show CI status for a single pull request.

Without an argument, the pull request that belongs to the current branch is selected.

When the --json flag is used, it includes a bucket field, which categorizes the state field into pass, fail, pending, skipping, or cancel.

Additional exit codes: 8: Checks pending

bucket, completedAt, description, event, link, name, startedAt, state, workflow

**Examples:**

Example 1 (unknown):
```unknown
gh pr checks [<number> | <url> | <branch>] [flags]
```

---

## gh pr ready

**URL:** https://cli.github.com/manual/gh_pr_ready

**Contents:**
- gh pr ready
  - Options
  - Options inherited from parent commands
  - See also

Mark a pull request as ready for review.

Without an argument, the pull request that belongs to the current branch is marked as ready.

If supported by your plan, convert to draft with --undo

**Examples:**

Example 1 (unknown):
```unknown
gh pr ready [<number> | <url> | <branch>] [flags]
```

---

## Gotchas

### Review threads and resolved state require GraphQL

`gh pr view` cannot show review threads or whether they are resolved, and thread IDs exist only in GraphQL. To count unresolved threads:

```bash
gh api graphql -f query='
  query($owner:String!, $repo:String!, $pr:Int!) {
    repository(owner:$owner, name:$repo) {
      pullRequest(number:$pr) {
        reviewThreads(first:100) { nodes { id isResolved } }
      }
    }
  }' -F owner=OWNER -F repo=REPO -F pr=123 \
  --jq '[.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved | not)] | length'
```

### `gh pr checks` can surface stale check runs

A cancelled or superseded run from an earlier push may still show as failing (often with a `0s` duration) even after a green re-run. Confirm against the latest run for the head SHA before declaring CI broken.

CI triage loop that works:

```bash
gh pr checks                              # find the failing check
gh run view --log-failed --job <job-id>   # read only the failing job's log
gh run rerun <run-id> --failed            # retry just the failed jobs
```

`gh run watch --exit-status` exits non-zero only when the run *concludes* failed - exit 0 means the run succeeded.

### `gh pr revert`

Reverts a merged pull request, opening a new PR with the reverting commit:

```bash
gh pr revert 123 --repo OWNER/REPO
```

# Gh-Cli - Releases

**Pages:** 9

---

## gh release delete

**URL:** https://cli.github.com/manual/gh_release_delete

**Contents:**
- gh release delete
  - Options
  - Options inherited from parent commands
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh release delete <tag> [flags]
```

---

## gh release upload

**URL:** https://cli.github.com/manual/gh_release_upload

**Contents:**
- gh release upload
  - Options
  - Options inherited from parent commands
  - See also

Upload asset files to a GitHub Release.

To define a display label for an asset, append text starting with # after the file name.

**Examples:**

Example 1 (unknown):
```unknown
gh release upload <tag> <files>... [flags]
```

---

## gh release delete-asset

**URL:** https://cli.github.com/manual/gh_release_delete-asset

**Contents:**
- gh release delete-asset
  - Options
  - Options inherited from parent commands
  - See also

Delete an asset from a release

**Examples:**

Example 1 (unknown):
```unknown
gh release delete-asset <tag> <asset-name> [flags]
```

---

## gh release view

**URL:** https://cli.github.com/manual/gh_release_view

**Contents:**
- gh release view
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also

View information about a GitHub Release.

Without an explicit tag name argument, the latest release in the project is shown.

apiUrl, assets, author, body, createdAt, databaseId, id, isDraft, isImmutable, isPrerelease, name, publishedAt, tagName, tarballUrl, targetCommitish, uploadUrl, url, zipballUrl

**Examples:**

Example 1 (unknown):
```unknown
gh release view [<tag>] [flags]
```

---

## gh release verify-asset

**URL:** https://cli.github.com/manual/gh_release_verify-asset

**Contents:**
- gh release verify-asset
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Verify that a given asset file originated from a specific GitHub Release using cryptographically signed attestations.

An attestation is a claim made by GitHub regarding a release and its assets.

**Examples:**

Example 1 (unknown):
```unknown
gh release verify-asset [<tag>] <file-path> [flags]
```

Example 2 (unknown):
```unknown
This command checks that the asset you provide matches a valid attestation for the specified release (or the latest release, if no tag is given). It ensures the asset's integrity by validating that the asset's digest matches the subject in the attestation and that the attestation is associated with the release.
```

Example 3 (bash):
```bash
# Verify an asset from the latest release
$ gh release verify-asset ./dist/my-asset.zip

# Verify an asset from a specific release tag
$ gh release verify-asset v1.2.3 ./dist/my-asset.zip

# Verify an asset from a specific release tag and output the attestation in JSON format
$ gh release verify-asset v1.2.3 ./dist/my-asset.zip --format json
```

---

## gh release download

**URL:** https://cli.github.com/manual/gh_release_download

**Contents:**
- gh release download
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Download assets from a GitHub release.

Without an explicit tag name argument, assets are downloaded from the latest release in the project. In this case, --pattern or --archive is required.

**Examples:**

Example 1 (unknown):
```unknown
gh release download [<tag>] [flags]
```

Example 2 (bash):
```bash
# Download all assets from a specific release
$ gh release download v1.2.3

# Download only Debian packages for the latest release
$ gh release download --pattern '*.deb'

# Specify multiple file patterns
$ gh release download -p '*.deb' -p '*.rpm'

# Download the archive of the source code for a release
$ gh release download v1.2.3 --archive=zip
```

---

## gh release edit

**URL:** https://cli.github.com/manual/gh_release_edit

**Contents:**
- gh release edit
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh release edit <tag>
```

Example 2 (bash):
```bash
# Publish a release that was previously a draft
$ gh release edit v1.0 --draft=false

# Update the release notes from the content of a file
$ gh release edit v1.0 --notes-file /path/to/release_notes.md
```

---

## gh release verify

**URL:** https://cli.github.com/manual/gh_release_verify

**Contents:**
- gh release verify
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Verify that a GitHub Release is accompanied by a valid cryptographically signed attestation.

An attestation is a claim made by GitHub regarding a release and its assets.

This command checks that the specified release (or the latest release, if no tag is given) has a valid attestation. It fetches the attestation for the release and prints metadata about all assets referenced in the attestation, including their digests.

**Examples:**

Example 1 (unknown):
```unknown
gh release verify [<tag>] [flags]
```

Example 2 (bash):
```bash
# Verify the latest release
gh release verify

# Verify a specific release by tag
gh release verify v1.2.3

# Verify a specific release by tag and output the attestation in JSON format
gh release verify v1.2.3 --format json
```

---

## gh release

**URL:** https://cli.github.com/manual/gh_release

**Contents:**
- gh release
  - General commands
  - Targeted commands
  - Options
  - See also

---

## Gotchas

### Downloading needs no auth on public repos

Since gh 2.96.0, `gh release download` works against public repositories without authentication, matching `gh extension install`. A token is still used when present.

```bash
gh release download v2.96.0 --repo cli/cli
```

### There is no upsert, and exit codes are coarse

`gh release create` has **no `--clobber`** (only `gh release upload` does), and exit code 1 covers everything - not found, already exists, transient API error alike. So the common `gh release view TAG || gh release create TAG` guard is unreliable.

Idempotent pattern - try create, fall back to edit:

```bash
gh release create "$TAG" --title "$TITLE" --notes "$NOTES" \
  || gh release edit "$TAG" --title "$TITLE" --notes "$NOTES"

gh release upload "$TAG" ./dist/* --clobber
```

### Draft orphans and immutable releases

If `gh release create TAG ./files` fails partway through uploading assets, it can leave a **draft release behind** and roll back partially. On repos with immutable releases enabled, the all-in-one create can fail outright while uploading its auto-generated `digests.txt`.

The robust sequence is draft -> upload -> publish:

```bash
gh release create "$TAG" --draft --title "$TITLE" --notes "$NOTES"
gh release upload "$TAG" ./dist/* --clobber
gh release edit "$TAG" --draft=false
```

# Remote Repository Analysis

Fetch files and analyze repositories without cloning them locally.

## Fetch Files Without Cloning

### Preferred: `gh repo read-file` / `gh repo read-dir`

These preview commands are purpose-built for reading a repo without cloning. They print raw content (no base64 step), accept `--ref` for any branch/tag/commit, and transparently handle files past the Contents API's 1MB inline limit.

```bash
# Read a file from the default branch
gh repo read-file path/file.ts --repo OWNER/REPO

# From a specific branch, tag, or commit
gh repo read-file path/file.ts --repo OWNER/REPO --ref v1.2.0

# Save straight to disk
gh repo read-file path/file.ts --repo OWNER/REPO --output ./file.ts

# List a directory
gh repo read-dir PATH --repo OWNER/REPO
gh repo read-dir PATH --repo OWNER/REPO --json name,size,type --jq '.[] | select(.type=="file") | .name'
```

`read-dir` JSON fields: `gitSHA, gitType, mode, modeOctal, name, nameRaw, path, pathRaw, size, submodule, type`.

### Fallback: the Contents API

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

# Or decode the base64 JSON response
gh api repos/OWNER/REPO/contents/path/file.ts --jq '.content' | base64 -d
```

There is no `base64decode` template function - `--template '{{.content | base64decode}}'` errors out. See `gh help formatting` for the functions that do exist.

### Cache repeated fetches

When iterating over the same files, cache responses so you do not re-spend the 5000/hr core budget:

```bash
gh api repos/OWNER/REPO/contents/PATH --cache 1h
```

Use `--slurp` with `--paginate` to collect all pages into a single JSON array:

```bash
gh api --paginate --slurp repos/OWNER/REPO/commits
```

### Get entire file tree recursively

```bash
gh api repos/OWNER/REPO/git/trees/main?recursive=1
```

Returns complete tree structure in one request.

## Useful Remote Analysis Patterns

### Check if file exists

```bash
gh api repos/OWNER/REPO/contents/path/file.ts 2>/dev/null && echo "exists" || echo "not found"
```

### Get latest commit for specific file

```bash
gh api repos/OWNER/REPO/commits?path=src/index.ts | jq -r '.[0].sha'
```

### Compare file across branches

```bash
gh api repos/OWNER/REPO/contents/file.ts?ref=main | jq -r '.content' | base64 -d > main.ts
gh api repos/OWNER/REPO/contents/file.ts?ref=dev | jq -r '.content' | base64 -d > dev.ts
diff main.ts dev.ts
```

### Get file from specific commit

```bash
gh api repos/OWNER/REPO/contents/file.ts?ref=abc123 | jq -r '.content' | base64 -d
```

Use any commit SHA, branch name, or tag as the `ref` parameter.

## Working with Large Repositories

For large repos, use the Git Trees API instead of Contents API:

```bash
# Get full tree
gh api repos/OWNER/REPO/git/trees/main?recursive=1 | jq '.tree[] | select(.type == "blob") | .path'
```

This is more efficient for listing many files.

## Common Use Cases

### Inspect configuration files

```bash
gh api repos/vercel/next.js/contents/package.json | jq -r '.content' | base64 -d | jq '.dependencies'
```

### Check documentation

```bash
gh api repos/anthropics/anthropic-sdk-python/contents/README.md | jq -r '.content' | base64 -d
```

### Analyze project structure

```bash
gh api repos/OWNER/REPO/git/trees/main?recursive=1 | jq -r '.tree[] | select(.type == "tree") | .path'
```

Shows all directories in the repository.

# Gh-Cli - Repositories

**Pages:** 72

---

## gh repo autolink

**URL:** https://cli.github.com/manual/gh_repo_autolink

**Contents:**
- gh repo autolink
  - Available commands
  - Options
  - See also

Autolinks link issues, pull requests, commit messages, and release descriptions to external third-party services.

Autolinks require admin role to view or manage.

For more information, see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources

---

## gh repo gitignore list

**URL:** https://cli.github.com/manual/gh_repo_gitignore_list

**Contents:**
- gh repo gitignore list
  - ALIASES
  - See also

List available repository gitignore templates

**Examples:**

Example 1 (unknown):
```unknown
gh repo gitignore list
```

---

## gh label list

**URL:** https://cli.github.com/manual/gh_label_list

**Contents:**
- gh label list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - Examples
  - See also

Display labels in a GitHub repository.

When using the --search flag results are sorted by best match of the query. This behavior cannot be configured with the --order or --sort flags.

color, createdAt, description, id, isDefault, name, updatedAt, url

**Examples:**

Example 1 (unknown):
```unknown
gh label list [flags]
```

Example 2 (bash):
```bash
# Sort labels by name
$ gh label list --sort name

# Find labels with "bug" in the name or description
$ gh label list --search bug
```

---

## gh repo rename

**URL:** https://cli.github.com/manual/gh_repo_rename

**Contents:**
- gh repo rename
  - Options
  - Examples
  - See also

Rename a GitHub repository.

<new-name> is the desired repository name without the owner.

By default, the current repository is renamed. Otherwise, the repository specified with --repo is renamed.

To transfer repository ownership to another user account or organization, you must follow additional steps on github.com.

For more information on transferring repository ownership, see: https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository

**Examples:**

Example 1 (unknown):
```unknown
gh repo rename [<new-name>] [flags]
```

Example 2 (bash):
```bash
# Rename the current repository (foo/bar -> foo/baz)
$ gh repo rename baz

# Rename the specified repository (qux/quux -> qux/baz)
$ gh repo rename -R qux/quux baz
```

---

## gh repo clone

**URL:** https://cli.github.com/manual/gh_repo_clone

**Contents:**
- gh repo clone
  - Options
  - Examples
  - See also
  - In use
    - Using OWNER/REPO syntax
    - Using other selectors

Clone a GitHub repository locally. Pass additional git clone flags by listing them after --.

If the OWNER/ portion of the OWNER/REPO repository argument is omitted, it defaults to the name of the authenticating user.

When a protocol scheme is not provided in the repository argument, the git_protocol will be chosen from your configuration, which can be checked via gh config get git_protocol. If the protocol scheme is provided, the repository will be cloned using the specified protocol.

If the repository is a fork, its parent repository will be added as an additional git remote called upstream. The remote name can be configured using --upstream-remote-name. The --upstream-remote-name option supports an @owner value which will name the remote after the owner of the parent repository.

If the repository is a fork, its parent repository will be set as the default remote repository.

You can clone any repository using OWNER/REPO syntax.

You can also use GitHub URLs to clone repositories.

**Examples:**

Example 1 (unknown):
```unknown
gh repo clone <repository> [<directory>] [-- <gitflags>...]
```

Example 2 (bash):
```bash
# Clone a repository from a specific org
$ gh repo clone cli/cli

# Clone a repository from your own account
$ gh repo clone myrepo

# Clone a repo, overriding git protocol configuration
$ gh repo clone https://github.com/cli/cli
$ gh repo clone git@github.com:cli/cli.git

# Clone a repository to a custom directory
$ gh repo clone cli/cli workspace/cli

# Clone a repository with additional git clone flags
$ gh repo clone cli/cli -- --depth=1
```

Example 3 (unknown):
```unknown
# Cloning a repository
~/Projects$ gh repo clone cli/cli
Cloning into 'cli'...
~/Projects$ cd cli
~/Projects/cli$
```

Example 4 (unknown):
```unknown
# Cloning a repository
~/Projects/my-project$ gh repo clone https://github.com/cli/cli
Cloning into 'cli'...
remote: Enumerating objects: 99, done.
remote: Counting objects: 100% (99/99), done.
remote: Compressing objects: 100% (76/76), done.
remote: Total 21160 (delta 49), reused 35 (delta 18), pack-reused 21061
Receiving objects: 100% (21160/21160), 57.93 MiB | 10.82 MiB/s, done.
Resolving deltas: 100% (16051/16051), done.

~/Projects/my-project$
```

---

## gh repo autolink list

**URL:** https://cli.github.com/manual/gh_repo_autolink_list

**Contents:**
- gh repo autolink list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

Gets all autolink references that are configured for a repository.

Information about autolinks is only available to repository administrators.

id, isAlphanumeric, keyPrefix, urlTemplate

**Examples:**

Example 1 (unknown):
```unknown
gh repo autolink list [flags]
```

---

## gh pr status

**URL:** https://cli.github.com/manual/gh_pr_status

**Contents:**
- gh pr status
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also
  - In use

Show status of relevant pull requests.

The status shows a summary of pull requests that includes information such as pull request number, title, CI checks, reviews, etc.

To see more details of CI checks, run gh pr checks.

additions, assignees, author, autoMergeRequest, baseRefName, baseRefOid, body, changedFiles, closed, closedAt, closingIssuesReferences, comments, commits, createdAt, deletions, files, fullDatabaseId, headRefName, headRefOid, headRepository, headRepositoryOwner, id, isCrossRepository, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, potentialMergeCommit, projectCards, projectItems, reactionGroups, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

**Examples:**

Example 1 (unknown):
```unknown
gh pr status [flags]
```

Example 2 (unknown):
```unknown
# Viewing the status of your relevant pull requests
~/Projects/my-project$ gh pr status
Current branch
  #12 Remove the test feature [user:patch-2]
   - All checks failing - Review required

Created by you
  You have no open pull requests

Requesting a code review from you
  #13 Fix tests [branch]
  - 3/4 checks failing - Review required
  #15 New feature [branch]
   - Checks passing - Approved

~/Projects/my-project$
```

---

## gh agent-task create

**URL:** https://cli.github.com/manual/gh_agent-task_create

**Contents:**
- gh agent-task create
  - Options
  - Examples
  - See also

Create an agent task (preview)

**Examples:**

Example 1 (unknown):
```unknown
gh agent-task create [<task description>] [flags]
```

Example 2 (bash):
```bash
# Create a task from an inline description
$ gh agent-task create "build me a new app"

# Create a task from an inline description and follow logs
$ gh agent-task create "build me a new app" --follow

# Create a task from a file
$ gh agent-task create -F task-desc.md

# Create a task with problem statement from stdin
$ echo "build me a new app" | gh agent-task create -F -

# Create a task with an editor
$ gh agent-task create

# Create a task with an editor and a file as a template
$ gh agent-task create -F task-desc.md

# Select a different base branch for the PR
$ gh agent-task create "fix errors" --base branch
```

---

## gh project unlink

**URL:** https://cli.github.com/manual/gh_project_unlink

**Contents:**
- gh project unlink
  - Options
  - Examples
  - See also

Unlink a project from a repository or a team

**Examples:**

Example 1 (unknown):
```unknown
gh project unlink [<number>] [flags]
```

Example 2 (bash):
```bash
# Unlink monalisa's project 1 from her repository "my_repo"
$ gh project unlink 1 --owner monalisa --repo my_repo

# Unlink monalisa's organization's project 1 from her team "my_team"
$ gh project unlink 1 --owner my_organization --team my_team

# Unlink monalisa's project 1 from the repository of current directory if neither --repo nor --team is specified
$ gh project unlink 1
```

---

## gh repo

**URL:** https://cli.github.com/manual/gh_repo

**Contents:**
- gh repo
  - General commands
  - Targeted commands
  - Examples
  - See also

Work with GitHub repositories.

**Examples:**

Example 1 (bash):
```bash
$ gh repo create
$ gh repo clone cli/cli
$ gh repo view --web
```

---

## gh project link

**URL:** https://cli.github.com/manual/gh_project_link

**Contents:**
- gh project link
  - Options
  - Examples
  - See also

Link a project to a repository or a team

**Examples:**

Example 1 (unknown):
```unknown
gh project link [<number>] [flags]
```

Example 2 (bash):
```bash
# Link monalisa's project 1 to her repository "my_repo"
$ gh project link 1 --owner monalisa --repo my_repo

# Link monalisa's organization's project 1 to her team "my_team"
$ gh project link 1 --owner my_organization --team my_team

# Link monalisa's project 1 to the repository of current directory if neither --repo nor --team is specified
$ gh project link 1
```

---

## gh repo autolink view

**URL:** https://cli.github.com/manual/gh_repo_autolink_view

**Contents:**
- gh repo autolink view
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also

View an autolink reference for a repository.

id, isAlphanumeric, keyPrefix, urlTemplate

**Examples:**

Example 1 (unknown):
```unknown
gh repo autolink view <id> [flags]
```

---

## gh label clone

**URL:** https://cli.github.com/manual/gh_label_clone

**Contents:**
- gh label clone
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Clones labels from a source repository to a destination repository on GitHub. By default, the destination repository is the current repository.

All labels from the source repository will be copied to the destination repository. Labels in the destination repository that are not in the source repository will not be deleted or modified.

Labels from the source repository that already exist in the destination repository will be skipped. You can overwrite existing labels in the destination repository using the --force flag.

**Examples:**

Example 1 (unknown):
```unknown
gh label clone <source-repository> [flags]
```

Example 2 (bash):
```bash
# Clone and overwrite labels from cli/cli repository into the current repository
$ gh label clone cli/cli --force

# Clone labels from cli/cli repository into a octocat/cli repository
$ gh label clone cli/cli --repo octocat/cli
```

---

## gh repo list

**URL:** https://cli.github.com/manual/gh_repo_list

**Contents:**
- gh repo list
  - Options
  - ALIASES
  - JSON Fields
  - See also

List repositories owned by a user or organization.

Note that the list will only include repositories owned by the provided argument, and the --fork or --source flags will not traverse ownership boundaries. For example, when listing the forks in an organization, the output would not include those owned by individual users.

archivedAt, assignableUsers, codeOfConduct, contactLinks, createdAt, defaultBranchRef, deleteBranchOnMerge, description, diskUsage, forkCount, fundingLinks, hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled, homepageUrl, id, isArchived, isBlankIssuesEnabled, isEmpty, isFork, isInOrganization, isMirror, isPrivate, isSecurityPolicyEnabled, isTemplate, isUserConfigurationRepository, issueTemplates, issues, labels, languages, latestRelease, licenseInfo, mentionableUsers, mergeCommitAllowed, milestones, mirrorUrl, name, nameWithOwner, openGraphImageUrl, owner, parent, primaryLanguage, projects, projectsV2, pullRequestTemplates, pullRequests, pushedAt, rebaseMergeAllowed, repositoryTopics, securityPolicyUrl, squashMergeAllowed, sshUrl, stargazerCount, templateRepository, updatedAt, url, usesCustomOpenGraphImage, viewerCanAdminister, viewerDefaultCommitEmail, viewerDefaultMergeMethod, viewerHasStarred, viewerPermission, viewerPossibleCommitEmails, viewerSubscription, visibility, watchers

**Examples:**

Example 1 (unknown):
```unknown
gh repo list [<owner>] [flags]
```

---

## gh issue unpin

**URL:** https://cli.github.com/manual/gh_issue_unpin

**Contents:**
- gh issue unpin
  - Options inherited from parent commands
  - Examples
  - See also

Unpin an issue from a repository.

The issue can be specified by issue number or URL.

**Examples:**

Example 1 (unknown):
```unknown
gh issue unpin {<number> | <url>}
```

Example 2 (bash):
```bash
# Unpin issue from the current repository
$ gh issue unpin 23

# Unpin issue by URL
$ gh issue unpin https://github.com/owner/repo/issues/23

# Unpin an issue from specific repository
$ gh issue unpin 23 --repo owner/repo
```

---

## gh repo view

**URL:** https://cli.github.com/manual/gh_repo_view

**Contents:**
- gh repo view
  - Options
  - JSON Fields
  - See also
  - In use
    - In terminal
    - In the browser
    - With no arguments

Display the description and the README of a GitHub repository.

With no argument, the repository for the current directory is displayed.

With --web, open the repository in a web browser instead.

With --branch, view a specific branch of the repository.

archivedAt, assignableUsers, codeOfConduct, contactLinks, createdAt, defaultBranchRef, deleteBranchOnMerge, description, diskUsage, forkCount, fundingLinks, hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled, homepageUrl, id, isArchived, isBlankIssuesEnabled, isEmpty, isFork, isInOrganization, isMirror, isPrivate, isSecurityPolicyEnabled, isTemplate, isUserConfigurationRepository, issueTemplates, issues, labels, languages, latestRelease, licenseInfo, mentionableUsers, mergeCommitAllowed, milestones, mirrorUrl, name, nameWithOwner, openGraphImageUrl, owner, parent, primaryLanguage, projects, projectsV2, pullRequestTemplates, pullRequests, pushedAt, rebaseMergeAllowed, repositoryTopics, securityPolicyUrl, squashMergeAllowed, sshUrl, stargazerCount, templateRepository, updatedAt, url, usesCustomOpenGraphImage, viewerCanAdminister, viewerDefaultCommitEmail, viewerDefaultMergeMethod, viewerHasStarred, viewerPermission, viewerPossibleCommitEmails, viewerSubscription, visibility, watchers

By default, we will display items in the terminal.

Quickly open an item in the browser using --web or -w

We will display the repository you're currently in.

**Examples:**

Example 1 (unknown):
```unknown
gh repo view [<repository>] [flags]
```

Example 2 (unknown):
```unknown
# Viewing a repository in terminal
~/Projects/my-project$ gh repo view owner/repo
owner/repo
Repository description

  Repository README

View this repository on GitHub: https://github.com/owner/repo/
~/Projects/my-project$
```

Example 3 (unknown):
```unknown
# Viewing a repository in the browser
~/Projects$ gh repo view owner/repo --web
Opening https://github.com/owner/repo/ in your browser.
~/Projects$
```

Example 4 (unknown):
```unknown
# Viewing the repository you're in
~/Projects/my-project$ gh repo view
owner/my-project
Repository description

  Repository README

View this repository on GitHub: https://github.com/owner/repo/
~/Projects/my-project$
```

---

## gh gist clone

**URL:** https://cli.github.com/manual/gh_gist_clone

**Contents:**
- gh gist clone
  - See also

Clone a GitHub gist locally.

A gist can be supplied as argument in either of the following formats:

Pass additional git clone flags by listing them after --.

**Examples:**

Example 1 (unknown):
```unknown
gh gist clone <gist> [<directory>] [-- <gitflags>...]
```

---

## gh codespace create

**URL:** https://cli.github.com/manual/gh_codespace_create

**Contents:**
- gh codespace create
  - Options
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh codespace create [flags]
```

---

## gh repo delete

**URL:** https://cli.github.com/manual/gh_repo_delete

**Contents:**
- gh repo delete
  - Options
  - See also

Delete a GitHub repository.

With no argument, deletes the current repository. Otherwise, deletes the specified repository.

For safety, when no repository argument is provided, the --yes flag is ignored and you will be prompted for confirmation. To delete the current repository non-interactively, specify it explicitly (e.g., gh repo delete owner/repo --yes).

Deletion requires authorization with the delete_repo scope. To authorize, run gh auth refresh -s delete_repo

**Examples:**

Example 1 (unknown):
```unknown
gh repo delete [<repository>] [flags]
```

---

## gh repo deploy-key add

**URL:** https://cli.github.com/manual/gh_repo_deploy-key_add

**Contents:**
- gh repo deploy-key add
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Add a deploy key to a GitHub repository.

Note that any key added by gh will be associated with the current authentication token. If you de-authorize the GitHub CLI app or authentication token from your account, any deploy keys added by GitHub CLI will be removed as well.

**Examples:**

Example 1 (unknown):
```unknown
gh repo deploy-key add <key-file> [flags]
```

Example 2 (bash):
```bash
# Generate a passwordless SSH key and add it as a deploy key to a repository
$ ssh-keygen -t ed25519 -C "my description" -N "" -f ~/.ssh/gh-test
$ gh repo deploy-key add ~/.ssh/gh-test.pub
```

---

## gh repo gitignore view

**URL:** https://cli.github.com/manual/gh_repo_gitignore_view

**Contents:**
- gh repo gitignore view
  - Examples
  - See also

View an available repository .gitignore template.

<template> is a case-sensitive .gitignore template name.

For a list of available templates, run gh repo gitignore list.

**Examples:**

Example 1 (unknown):
```unknown
gh repo gitignore view <template>
```

Example 2 (bash):
```bash
# View the Go gitignore template
$ gh repo gitignore view Go

# View the Python gitignore template
$ gh repo gitignore view Python

# Create a new .gitignore file using the Go template
$ gh repo gitignore view Go > .gitignore

# Create a new .gitignore file using the Python template
$ gh repo gitignore view Python > .gitignore
```

---

## gh issue edit

**URL:** https://cli.github.com/manual/gh_issue_edit

**Contents:**
- gh issue edit
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Edit one or more issues within the same repository.

Editing issues' projects requires authorization with the project scope. To authorize, run gh auth refresh -s project.

The --add-assignee and --remove-assignee flags both support the following special values:

**Examples:**

Example 1 (unknown):
```unknown
gh issue edit {<numbers> | <urls>} [flags]
```

Example 2 (bash):
```bash
$ gh issue edit 23 --title "I found a bug" --body "Nothing works"
$ gh issue edit 23 --add-label "bug,help wanted" --remove-label "core"
$ gh issue edit 23 --add-assignee "@me" --remove-assignee monalisa,hubot
$ gh issue edit 23 --add-assignee "@copilot"
$ gh issue edit 23 --add-project "Roadmap" --remove-project v1,v2
$ gh issue edit 23 --milestone "Version 1"
$ gh issue edit 23 --remove-milestone
$ gh issue edit 23 --body-file body.txt
$ gh issue edit 23 34 --add-label "help wanted"
```

---

## gh release list

**URL:** https://cli.github.com/manual/gh_release_list

**Contents:**
- gh release list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List releases in a repository

createdAt, isDraft, isLatest, isPrerelease, name, publishedAt, tagName

**Examples:**

Example 1 (unknown):
```unknown
gh release list [flags]
```

---

## gh variable list

**URL:** https://cli.github.com/manual/gh_variable_list

**Contents:**
- gh variable list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List variables on one of the following levels:

createdAt, name, numSelectedRepos, selectedReposURL, updatedAt, value, visibility

**Examples:**

Example 1 (unknown):
```unknown
gh variable list [flags]
```

---

## gh project item-create

**URL:** https://cli.github.com/manual/gh_project_item-create

**Contents:**
- gh project item-create
  - Options
  - Examples
  - See also

Create a draft issue item in a project

**Examples:**

Example 1 (unknown):
```unknown
gh project item-create [<number>] [flags]
```

Example 2 (bash):
```bash
# Create a draft issue in the current user's project "1"
$ gh project item-create 1 --owner "@me" --title "new item" --body "new item body"
```

---

## gh repo deploy-key

**URL:** https://cli.github.com/manual/gh_repo_deploy-key

**Contents:**
- gh repo deploy-key
  - Available commands
  - Options
  - See also

Manage deploy keys in a repository

---

## gh repo sync

**URL:** https://cli.github.com/manual/gh_repo_sync

**Contents:**
- gh repo sync
  - Options
  - Examples
  - See also

Sync destination repository from source repository. Syncing uses the default branch of the source repository to update the matching branch on the destination repository so they are equal. A fast forward update will be used except when the --force flag is specified, then the two branches will be synced using a hard reset.

Without an argument, the local repository is selected as the destination repository.

The source repository is the parent of the destination repository by default. This can be overridden with the --source flag.

**Examples:**

Example 1 (unknown):
```unknown
gh repo sync [<destination-repository>] [flags]
```

Example 2 (bash):
```bash
# Sync local repository from remote parent
$ gh repo sync

# Sync local repository from remote parent on specific branch
$ gh repo sync --branch v1

# Sync remote fork from its parent
$ gh repo sync owner/cli-fork

# Sync remote repository from another remote repository
$ gh repo sync owner/repo --source owner2/repo2
```

---

## gh codespace list

**URL:** https://cli.github.com/manual/gh_codespace_list

**Contents:**
- gh codespace list
  - Options
  - ALIASES
  - JSON Fields
  - See also

List codespaces of the authenticated user.

Alternatively, organization administrators may list all codespaces billed to the organization.

gh cs ls, gh codespace ls

createdAt, displayName, gitStatus, lastUsedAt, machineName, name, owner, repository, state, vscsTarget

**Examples:**

Example 1 (unknown):
```unknown
gh codespace list [flags]
```

---

## gh variable

**URL:** https://cli.github.com/manual/gh_variable

**Contents:**
- gh variable
  - Available commands
  - Options
  - See also

Variables can be set at the repository, environment or organization level for use in GitHub Actions or Dependabot. Run gh help variable set to learn how to get started.

---

## gh pr checkout

**URL:** https://cli.github.com/manual/gh_pr_checkout

**Contents:**
- gh pr checkout
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also
  - In use
    - Using pull request number
    - Using other selectors

Check out a pull request in git

You can check out any pull request, including from forks, in a repository using its pull request number

You can also use URLs and branch names to checkout pull requests.

**Examples:**

Example 1 (unknown):
```unknown
gh pr checkout [<number> | <url> | <branch>] [flags]
```

Example 2 (bash):
```bash
# Interactively select a PR from the 10 most recent to check out
$ gh pr checkout

# Checkout a specific PR
$ gh pr checkout 32
$ gh pr checkout https://github.com/OWNER/REPO/pull/32
$ gh pr checkout feature
```

Example 3 (unknown):
```unknown
// Checking out a pull request locally
~/Projects/my-project$ gh pr checkout 12
remote: Enumerating objects: 66, done.
remote: Counting objects: 100% (66/66), done.
remote: Total 83 (delta 66), reused 66 (delta 66), pack-reused 17
Unpacking objects: 100% (83/83), done.
From https://github.com/owner/repo
 * [new ref]             refs/pull/8896/head -> patch-2
M       README.md
Switched to branch 'patch-2'

~/Projects/my-project$
```

Example 4 (unknown):
```unknown
// Checking out a pull request locally
~/Projects/my-project$ gh pr checkout branch-name
Switched to branch 'branch-name'
Your branch is up to date with 'origin/branch-name'.
Already up to date.

~/Projects/my-project$
```

---

## gh repo archive

**URL:** https://cli.github.com/manual/gh_repo_archive

**Contents:**
- gh repo archive
  - Options
  - See also

Archive a GitHub repository.

With no argument, archives the current repository.

**Examples:**

Example 1 (unknown):
```unknown
gh repo archive [<repository>] [flags]
```

---

## gh release create

**URL:** https://cli.github.com/manual/gh_release_create

**Contents:**
- gh release create
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also

Create a new GitHub Release for a repository.

A list of asset files may be given to upload to the new release. To define a display label for an asset, append text starting with # after the file name.

If a matching git tag does not yet exist, one will automatically get created from the latest state of the default branch. Use --target to point to a different branch or commit for the automatic tag creation. Use --verify-tag to abort the release if the tag doesn't already exist. To fetch the new tag locally after the release, do git fetch --tags origin.

To create a release from an annotated git tag, first create one locally with git, push the tag to GitHub, then run this command. Use --notes-from-tag to get the release notes from the annotated git tag. If the tag is not annotated, the commit message will be used instead.

Use --generate-notes to automatically generate notes using GitHub Release Notes API. When using automatically generated release notes, a release title will also be automatically generated unless a title was explicitly passed. Additional release notes can be prepended to automatically generated notes by using the --notes flag.

By default, the release is created even if there are no new commits since the last release. This may result in the same or duplicate release which may not be desirable in some cases. Use --fail-on-no-commits to fail if no new commits are available. This flag has no effect if there are no existing releases or this is the very first release.

**Examples:**

Example 1 (unknown):
```unknown
gh release create [<tag>] [<filename>... | <pattern>...]
```

Example 2 (bash):
```bash
# Interactively create a release
$ gh release create

# Interactively create a release from specific tag
$ gh release create v1.2.3

# Non-interactively create a release
$ gh release create v1.2.3 --notes "bugfix release"

# Use automatically generated via GitHub Release Notes API release notes
$ gh release create v1.2.3 --generate-notes

# Use release notes from a file
$ gh release create v1.2.3 -F release-notes.md

# Use tag annotation or associated commit message as notes
$ gh release create v1.2.3 --notes-from-tag

# Don't mark the release as latest
$ gh release create v1.2.3 --latest=false

# Upload all tarballs in a directory as release assets
$ gh release create v1.2.3 ./dist/*.tgz

# Upload a release asset with a display label
$ gh release create v1.2.3 '/path/to/asset.zip#My display label'

# Create a release and start a discussion
$ gh release create v1.2.3 --discussion-category "General"

# Create a release only if there are new commits available since the last release
$ gh release create v1.2.3 --fail-on-no-commits
```

---

## gh issue pin

**URL:** https://cli.github.com/manual/gh_issue_pin

**Contents:**
- gh issue pin
  - Options inherited from parent commands
  - Examples
  - See also

Pin an issue to a repository.

The issue can be specified by issue number or URL.

**Examples:**

Example 1 (unknown):
```unknown
gh issue pin {<number> | <url>}
```

Example 2 (bash):
```bash
# Pin an issue to the current repository
$ gh issue pin 23

# Pin an issue by URL
$ gh issue pin https://github.com/owner/repo/issues/23

# Pin an issue to specific repository
$ gh issue pin 23 --repo owner/repo
```

---

## gh repo deploy-key delete

**URL:** https://cli.github.com/manual/gh_repo_deploy-key_delete

**Contents:**
- gh repo deploy-key delete
  - Options inherited from parent commands
  - See also

Delete a deploy key from a GitHub repository

**Examples:**

Example 1 (unknown):
```unknown
gh repo deploy-key delete <key-id>
```

---

## gh extension

**URL:** https://cli.github.com/manual/gh_extension

**Contents:**
- gh extension
  - Available commands
  - ALIASES
  - See also

GitHub CLI extensions are repositories that provide additional gh commands.

The name of the extension repository must start with gh- and it must contain an executable of the same name. All arguments passed to the gh <extname> invocation will be forwarded to the gh-<extname> executable of the extension.

An extension cannot override any of the core gh commands. If an extension name conflicts with a core gh command, you can use gh extension exec <extname>.

When an extension is executed, gh will check for new versions once every 24 hours and display an upgrade notice. See gh help environment for information on disabling extension notices.

For the list of available extensions, see https://github.com/topics/gh-extension.

gh ext, gh extensions

---

## gh ruleset check

**URL:** https://cli.github.com/manual/gh_ruleset_check

**Contents:**
- gh ruleset check
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

View information about GitHub rules that apply to a given branch.

The provided branch name does not need to exist; rules will be displayed that would apply to a branch with that name. All rules are returned regardless of where they are configured.

If no branch name is provided, then the current branch will be used.

The --default flag can be used to view rules that apply to the default branch of the repository.

**Examples:**

Example 1 (unknown):
```unknown
gh ruleset check [<branch>] [flags]
```

Example 2 (bash):
```bash
# View all rules that apply to the current branch
$ gh ruleset check

# View all rules that apply to a branch named "my-branch" in a different repository
$ gh ruleset check my-branch --repo owner/repo

# View all rules that apply to the default branch in a different repository
$ gh ruleset check --default --repo owner/repo

# View a ruleset configured in a different repository or any of its parents
$ gh ruleset view 23 --repo owner/repo

# View an organization-level ruleset
$ gh ruleset view 23 --org my-org
```

---

## gh codespace delete

**URL:** https://cli.github.com/manual/gh_codespace_delete

**Contents:**
- gh codespace delete
  - Options
  - See also

Delete codespaces based on selection criteria.

All codespaces for the authenticated user can be deleted, as well as codespaces for a specific repository. Alternatively, only codespaces older than N days can be deleted.

Organization administrators may delete any codespace billed to the organization.

**Examples:**

Example 1 (unknown):
```unknown
gh codespace delete [flags]
```

---

## gh pr list

**URL:** https://cli.github.com/manual/gh_pr_list

**Contents:**
- gh pr list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - Examples
  - See also
  - In use
    - Default behavior
    - Filtering with flags

List pull requests in a GitHub repository. By default, this only lists open PRs.

The search query syntax is documented here: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests

On supported GitHub hosts, advanced issue search syntax can be used in the --search query. For more information about advanced issue search, see: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues

additions, assignees, author, autoMergeRequest, baseRefName, baseRefOid, body, changedFiles, closed, closedAt, closingIssuesReferences, comments, commits, createdAt, deletions, files, fullDatabaseId, headRefName, headRefOid, headRepository, headRepositoryOwner, id, isCrossRepository, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, potentialMergeCommit, projectCards, projectItems, reactionGroups, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

You will see the most recent 30 open items.

You can use flags to filter the list for your specific use cases.

**Examples:**

Example 1 (unknown):
```unknown
gh pr list [flags]
```

Example 2 (bash):
```bash
# List PRs authored by you
$ gh pr list --author "@me"

# List PRs with a specific head branch name
$ gh pr list --head "typo"

# List only PRs with all of the given labels
$ gh pr list --label bug --label "priority 1"

# Filter PRs using search syntax
$ gh pr list --search "status:success review:required"

# Find a PR that introduced a given commit
$ gh pr list --search "<SHA>" --state merged
```

Example 3 (unknown):
```unknown
# Viewing a list of open pull requests
~/Projects/my-project$ gh pr list

Pull requests for owner/repo

#14  Upgrade to Prettier 1.19                           prettier
#14  Extend arrow navigation in lists for MacOS         arrow-nav
#13  Add Support for Windows Automatic Dark Mode        dark-mode
#8   Create and use keyboard shortcut react component   shortcut

~/Projects/my-project$
```

Example 4 (unknown):
```unknown
# Viewing a list of closed pull requests assigned to a user
~/Projects/my-project$ gh pr list --state closed --assignee user

Pull requests for owner/repo

#13  Upgrade to Electron 7         electron-7
#8   Release Notes Writing Guide   release-notes

~/Projects/my-project$
```

---

## gh issue transfer

**URL:** https://cli.github.com/manual/gh_issue_transfer

**Contents:**
- gh issue transfer
  - Options inherited from parent commands
  - See also

Transfer issue to another repository

**Examples:**

Example 1 (unknown):
```unknown
gh issue transfer {<number> | <url>} <destination-repo>
```

---

## gh extension exec

**URL:** https://cli.github.com/manual/gh_extension_exec

**Contents:**
- gh extension exec
  - Examples
  - See also

Execute an extension using the short name. For example, if the extension repository is owner/gh-extension, you should pass extension. You can use this command when the short name conflicts with a core gh command.

All arguments after the extension name will be forwarded to the executable of the extension.

**Examples:**

Example 1 (unknown):
```unknown
gh extension exec <name> [args]
```

Example 2 (bash):
```bash
# Execute a label extension instead of the core gh label command
$ gh extension exec label
```

---

## gh extension create

**URL:** https://cli.github.com/manual/gh_extension_create

**Contents:**
- gh extension create
  - Options
  - Examples
  - See also

Create a new extension

**Examples:**

Example 1 (unknown):
```unknown
gh extension create [<name>] [flags]
```

Example 2 (bash):
```bash
# Use interactively
$ gh extension create

# Create a script-based extension
$ gh extension create foobar

# Create a Go extension
$ gh extension create --precompiled=go foobar

# Create a non-Go precompiled extension
$ gh extension create --precompiled=other foobar
```

---

## gh repo create

**URL:** https://cli.github.com/manual/gh_repo_create

**Contents:**
- gh repo create
  - Options
  - ALIASES
  - Examples
  - See also

Create a new GitHub repository.

To create a repository interactively, use gh repo create with no arguments.

To create a remote repository non-interactively, supply the repository name and one of --public, --private, or --internal. Pass --clone to clone the new repository locally.

If the OWNER/ portion of the OWNER/REPO name argument is omitted, it defaults to the name of the authenticating user.

To create a remote repository from an existing local repository, specify the source directory with --source. By default, the remote repository name will be the name of the source directory.

Pass --push to push any local commits to the new repository. If the repo is bare, this will mirror all refs.

For language or platform .gitignore templates to use with --gitignore, https://github.com/github/gitignore.

For license keywords to use with --license, run gh repo license list or visit https://choosealicense.com.

The repo is created with the configured repository default branch, see https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories.

**Examples:**

Example 1 (unknown):
```unknown
gh repo create [<name>] [flags]
```

Example 2 (bash):
```bash
# Create a repository interactively
$ gh repo create

# Create a new remote repository and clone it locally
$ gh repo create my-project --public --clone

# Create a new remote repository in a different organization
$ gh repo create my-org/my-project --public

# Create a remote repository from the current directory
$ gh repo create my-project --private --source=. --remote=upstream
```

---

## gh issue list

**URL:** https://cli.github.com/manual/gh_issue_list

**Contents:**
- gh issue list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - Examples
  - See also
  - In use
    - Default behavior
    - Filtering with flags

List issues in a GitHub repository. By default, this only lists open issues.

The search query syntax is documented here: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests

On supported GitHub hosts, advanced issue search syntax can be used in the --search query. For more information about advanced issue search, see: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues

assignees, author, body, closed, closedAt, closedByPullRequestsReferences, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

You will see the most recent 30 open items.

You can use flags to filter the list for your specific use cases.

**Examples:**

Example 1 (unknown):
```unknown
gh issue list [flags]
```

Example 2 (bash):
```bash
$ gh issue list --label "bug" --label "help wanted"
$ gh issue list --author monalisa
$ gh issue list --assignee "@me"
$ gh issue list --milestone "The big 1.0"
$ gh issue list --search "error no:assignee sort:created-asc"
$ gh issue list --state all
```

Example 3 (unknown):
```unknown
# Viewing a list of open issues
~/Projects/my-project$ gh issue list

Issues for owner/repo

#14  Update the remote url if it changed  (bug)
#14  PR commands on a detached head       (enhancement)
#13  Support for GitHub Enterprise        (wontfix)
#8   Add an easier upgrade command        (bug)

~/Projects/my-project$
```

Example 4 (unknown):
```unknown
# Viewing a list of closed issues assigned to a user
~/Projects/my-project$ gh issue list --state closed --assignee user

Issues for owner/repo

#13  Enable discarding submodule changes  (bug)
#8   Upgrade to latest react              (upgrade)

~/Projects/my-project$
```

---

## gh repo deploy-key list

**URL:** https://cli.github.com/manual/gh_repo_deploy-key_list

**Contents:**
- gh repo deploy-key list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - JSON Fields
  - See also

List deploy keys in a GitHub repository

gh repo deploy-key ls

createdAt, id, key, readOnly, title

**Examples:**

Example 1 (unknown):
```unknown
gh repo deploy-key list [flags]
```

---

## gh codespace view

**URL:** https://cli.github.com/manual/gh_codespace_view

**Contents:**
- gh codespace view
  - Options
  - JSON Fields
  - Examples
  - See also

View details about a codespace

billableOwner, createdAt, devcontainerPath, displayName, environmentId, gitStatus, idleTimeoutMinutes, lastUsedAt, location, machineDisplayName, machineName, name, owner, prebuild, recentFolders, repository, retentionExpiresAt, retentionPeriodDays, state, vscsTarget

**Examples:**

Example 1 (unknown):
```unknown
gh codespace view [flags]
```

Example 2 (bash):
```bash
# Select a codespace from a list of all codespaces you own
$ gh cs view

# View the details of a specific codespace
$ gh cs view -c codespace-name-12345

# View the list of all available fields for a codespace
$ gh cs view --json

# View specific fields for a codespace
$ gh cs view --json displayName,machineDisplayName,state
```

---

## gh label create

**URL:** https://cli.github.com/manual/gh_label_create

**Contents:**
- gh label create
  - Options
  - Options inherited from parent commands
  - Examples
  - See also

Create a new label on GitHub, or update an existing one with --force.

Must specify name for the label. The description and color are optional. If a color isn't provided, a random one will be chosen.

The label color needs to be 6 character hex value.

**Examples:**

Example 1 (unknown):
```unknown
gh label create <name> [flags]
```

Example 2 (bash):
```bash
# Create new bug label
$ gh label create bug --description "Something isn't working" --color E99695
```

---

## gh variable get

**URL:** https://cli.github.com/manual/gh_variable_get

**Contents:**
- gh variable get
  - Options
  - Options inherited from parent commands
  - JSON Fields
  - See also

Get a variable on one of the following levels:

createdAt, name, numSelectedRepos, selectedReposURL, updatedAt, value, visibility

**Examples:**

Example 1 (unknown):
```unknown
gh variable get <variable-name> [flags]
```

---

## gh project create

**URL:** https://cli.github.com/manual/gh_project_create

**Contents:**
- gh project create
  - Options
  - Examples
  - See also

**Examples:**

Example 1 (unknown):
```unknown
gh project create [flags]
```

Example 2 (bash):
```bash
# Create a new project owned by login monalisa
$ gh project create --owner monalisa --title "a new project"
```

---

## gh pr create

**URL:** https://cli.github.com/manual/gh_pr_create

**Contents:**
- gh pr create
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also
  - In use
    - Interactively
    - With flags
    - In the browser

Create a pull request on GitHub.

Upon success, the URL of the created pull request will be printed.

When the current branch isn't fully pushed to a git remote, a prompt will ask where to push the branch and offer an option to fork the base repository. Use --head to explicitly skip any forking or pushing behavior.

--head supports <user>:<branch> syntax to select a head repo owned by <user>. Using an organization as the <user> is currently not supported. For more information, see https://github.com/cli/cli/issues/10093

A prompt will also ask for the title and the body of the pull request. Use --title and --body to skip this, or use --fill to autofill these values from git commits. It's important to notice that if the --title and/or --body are also provided alongside --fill, the values specified by --title and/or --body will take precedence and overwrite any autofilled content.

The base branch for the created PR can be specified using the --base flag. If not provided, the value of gh-merge-base git branch config will be used. If not configured, the repository's default branch will be used. Run git config branch.{current}.gh-merge-base {base} to configure the current branch to use the specified merge base.

Link an issue to the pull request by referencing the issue in the body of the pull request. If the body text mentions Fixes #123 or Closes #123, the referenced issue will automatically get closed when the pull request gets merged.

By default, users with write access to the base repository can push new commits to the head branch of the pull request. Disable this with --no-maintainer-edit.

Adding a pull request to projects requires authorization with the project scope. To authorize, run gh auth refresh -s project.

This command will automatically create a fork for you if you're in a repository that you don't have permission to push to.

**Examples:**

Example 1 (unknown):
```unknown
gh pr create [flags]
```

Example 2 (bash):
```bash
$ gh pr create --title "The bug is fixed" --body "Everything works again"
$ gh pr create --reviewer monalisa,hubot  --reviewer myorg/team-name
$ gh pr create --project "Roadmap"
$ gh pr create --base develop --head monalisa:feature
$ gh pr create --template "pull_request_template.md"
```

Example 3 (unknown):
```unknown
# Create a pull request interactively
~/Projects/my-project$ gh pr create
Creating pull request for feature-branch into main in owner/repo
? Title My new pull request
? Body [(e) to launch nano, enter to skip]
http://github.com/owner/repo/pull/1
~/Projects/my-project$
```

Example 4 (unknown):
```unknown
# Create a pull request using flags
~/Projects/my-project$ gh pr create --title "Pull request title" --body "Pull request body"
http://github.com/owner/repo/pull/1
~/Projects/my-project$
```

---

## gh repo autolink delete

**URL:** https://cli.github.com/manual/gh_repo_autolink_delete

**Contents:**
- gh repo autolink delete
  - Options
  - Options inherited from parent commands
  - See also

Delete an autolink reference for a repository.

**Examples:**

Example 1 (unknown):
```unknown
gh repo autolink delete <id> [flags]
```

---

## gh api

**URL:** https://cli.github.com/manual/gh_api

**Contents:**
- gh api
  - Options
  - Examples
  - See also

Makes an authenticated HTTP request to the GitHub API and prints the response.

The endpoint argument should either be a path of a GitHub API v3 endpoint, or graphql to access the GitHub API v4.

Placeholder values {owner}, {repo}, and {branch} in the endpoint argument will get replaced with values from the repository of the current directory or the repository specified in the GH_REPO environment variable. Note that in some shells, for example PowerShell, you may need to enclose any value that contains {...} in quotes to prevent the shell from applying special meaning to curly braces.

The -p/--preview flag enables opting into previews, which are feature-flagged, experimental API endpoints or behaviors. The API expects opt-in via the Accept header with format application/vnd.github.<preview-name>-preview+json and this command facilitates that via --preview <preview-name>. To send a request for the corsair and scarlet witch previews, you could use -p corsair,scarlet-witch or --preview corsair --preview scarlet-witch.

The default HTTP request method is GET normally and POST if any parameters were added. Override the method with --method.

Pass one or more -f/--raw-field values in key=value format to add static string parameters to the request payload. To add non-string or placeholder-determined values, see -F/--field below. Note that adding request parameters will automatically switch the request method to POST. To send the parameters as a GET query string instead, use --method GET.

The -F/--field flag has magic type conversion based on the format of the value:

For GraphQL requests, all fields other than query and operationName are interpreted as GraphQL variables.

To pass nested parameters in the request payload, use key[subkey]=value syntax when declaring fields. To pass nested values as arrays, declare multiple fields with the syntax key[]=value1, key[]=value2. To pass an empty array, use key[] without a value.

To pass pre-constructed JSON or payloads in other formats, a request body may be read from file specified by --input. Use - to read from standard input. When passing the request body this way, any parameters specified via field flags are added to the query string of the endpoint URL.

In --paginate mode, all pages of results will sequentially be requested until there are no more pages of results. For GraphQL requests, this requires that the original query accepts an $endCursor: String variable and that it fetches the pageInfo{ hasNextPage, endCursor } set of fields from a collection. Each page is a separate JSON array or object. Pass --slurp to wrap all pages of JSON arrays or objects into an outer JSON array.

**Examples:**

Example 1 (unknown):
```unknown
gh api <endpoint> [flags]
```

Example 2 (bash):
```bash
# List releases in the current repository
$ gh api repos/{owner}/{repo}/releases

# Post an issue comment
$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'

# Post nested parameter read from a file
$ gh api gists -F 'files[myfile.txt][content]=@myfile.txt'

# Add parameters to a GET request
$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'

# Set a custom HTTP header
$ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...

# Opt into GitHub API previews
$ gh api --preview baptiste,nebula ...

# Print only specific fields from the response
$ gh api repos/{owner}/{repo}/issues --jq '.[].title'

# Use a template for the output
$ gh api repos/{owner}/{repo}/issues --template \
  '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'

# Update allowed values of the "environment" custom property in a deeply nested array
$ gh api -X PATCH /orgs/{org}/properties/schema \
   -F 'properties[][property_name]=environment' \
   -F 'properties[][default_value]=production' \
   -F 'properties[][allowed_values][]=staging' \
   -F 'properties[][allowed_values][]=production'

# List releases with GraphQL
$ gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
  query($name: String!, $owner: String!) {
    repository(owner: $owner, name: $name) {
      releases(last: 3) {
        nodes { tagName }
      }
    }
  }
'

# List all repositories for a user
$ gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
'

# Get the percentage of forks for the current user
$ gh api graphql --paginate --slurp -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { isFork }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
' | jq 'def count(e): reduce e as $_ (0;.+1);
[.[].data.viewer.repositories.nodes[]] as $r | count(select($r[].isFork))/count($r[])'
```

---

## gh ruleset list

**URL:** https://cli.github.com/manual/gh_ruleset_list

**Contents:**
- gh ruleset list
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also

List GitHub rulesets for a repository or organization.

If no options are provided, the current repository's rulesets are listed. You can query a different repository's rulesets by using the --repo flag. You can also use the --org flag to list rulesets configured for the provided organization.

Use the --parents flag to control whether rulesets configured at higher levels that also apply to the provided repository or organization should be returned. The default is true.

Your access token must have the admin:org scope to use the --org flag, which can be granted by running gh auth refresh -s admin:org.

gh ruleset ls, gh rs ls

**Examples:**

Example 1 (unknown):
```unknown
gh ruleset list [flags]
```

Example 2 (bash):
```bash
# List rulesets in the current repository
$ gh ruleset list

# List rulesets in a different repository, including those configured at higher levels
$ gh ruleset list --repo owner/repo --parents

# List rulesets in an organization
$ gh ruleset list --org org-name
```

---

## gh issue create

**URL:** https://cli.github.com/manual/gh_issue_create

**Contents:**
- gh issue create
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also
  - In use
    - Interactively
    - With flags
    - In the browser

Create an issue on GitHub.

Adding an issue to projects requires authorization with the project scope. To authorize, run gh auth refresh -s project.

The --assignee flag supports the following special values:

**Examples:**

Example 1 (unknown):
```unknown
gh issue create [flags]
```

Example 2 (bash):
```bash
$ gh issue create --title "I found a bug" --body "Nothing works"
$ gh issue create --label "bug,help wanted"
$ gh issue create --label bug --label "help wanted"
$ gh issue create --assignee monalisa,hubot
$ gh issue create --assignee "@me"
$ gh issue create --assignee "@copilot"
$ gh issue create --project "Roadmap"
$ gh issue create --template "Bug Report"
```

Example 3 (unknown):
```unknown
# Create an issue interactively
~/Projects/my-project$ gh issue create
Creating issue in owner/repo
? Title My new issue
? Body [(e) to launch nano, enter to skip]
http://github.com/owner/repo/issues/1
~/Projects/my-project$
```

Example 4 (unknown):
```unknown
# Create an issue using flags
~/Projects/my-project$ gh issue create --title "Issue title" --body "Issue body"
http://github.com/owner/repo/issues/1
~/Projects/my-project$
```

---

## gh repo license list

**URL:** https://cli.github.com/manual/gh_repo_license_list

**Contents:**
- gh repo license list
  - ALIASES
  - See also

List common repository licenses.

For even more licenses, visit https://choosealicense.com/appendix

**Examples:**

Example 1 (unknown):
```unknown
gh repo license list
```

---

## gh attestation download

**URL:** https://cli.github.com/manual/gh_attestation_download

**Contents:**
- gh attestation download
  - NOTE: This feature is currently in public preview, and subject to change.
  - Options
  - Examples
  - See also

Download attestations associated with an artifact for offline use.

The command requires either:

In addition, the command requires either:

The --repo flag value must match the name of the GitHub repository that the artifact is linked with.

The --owner flag value must match the name of the GitHub organization that the artifact's linked repository belongs to.

Any associated bundle(s) will be written to a file in the current directory named after the artifact's digest. For example, if the digest is "sha256:1234", the file will be named "sha256:1234.jsonl".

Colons are special characters on Windows and cannot be used in file names. To accommodate, a dash will be used to separate the algorithm from the digest in the attestations file name. For example, if the digest is "sha256:1234", the file will be named "sha256-1234.jsonl".

**Examples:**

Example 1 (unknown):
```unknown
gh attestation download [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]
```

Example 2 (bash):
```bash
# Download attestations for a local artifact linked with an organization
$ gh attestation download example.bin -o github

# Download attestations for a local artifact linked with a repository
$ gh attestation download example.bin -R github/example

# Download attestations for an OCI image linked with an organization
$ gh attestation download oci://example.com/foo/bar:latest -o github
```

---

## gh repo unarchive

**URL:** https://cli.github.com/manual/gh_repo_unarchive

**Contents:**
- gh repo unarchive
  - Options
  - See also

Unarchive a GitHub repository.

With no argument, unarchives the current repository.

**Examples:**

Example 1 (unknown):
```unknown
gh repo unarchive [<repository>] [flags]
```

---

## gh gist create

**URL:** https://cli.github.com/manual/gh_gist_create

**Contents:**
- gh gist create
  - Options
  - ALIASES
  - Examples
  - See also

Create a new GitHub gist with given contents.

Gists can be created from one or multiple files. Alternatively, pass - as filename to read from standard input.

By default, gists are secret; use --public to make publicly listed ones.

**Examples:**

Example 1 (unknown):
```unknown
gh gist create [<filename>... | <pattern>... | -] [flags]
```

Example 2 (bash):
```bash
# Publish file 'hello.py' as a public gist
$ gh gist create --public hello.py

# Create a gist with a description
$ gh gist create hello.py -d "my Hello-World program in Python"

# Create a gist containing several files
$ gh gist create hello.py world.py cool.txt

# Create a gist containing several files using patterns
$ gh gist create *.md *.txt artifact.*

# Read from standard input to create a gist
$ gh gist create -

# Create a gist from output piped from another command
$ cat cool.txt | gh gist create
```

---

## gh repo license view

**URL:** https://cli.github.com/manual/gh_repo_license_view

**Contents:**
- gh repo license view
  - Options
  - Examples
  - See also

View a specific repository license by license key or SPDX ID.

Run gh repo license list to see available commonly used licenses. For even more licenses, visit https://choosealicense.com/appendix.

**Examples:**

Example 1 (unknown):
```unknown
gh repo license view {<license-key> | <spdx-id>} [flags]
```

Example 2 (bash):
```bash
# View the MIT license from SPDX ID
$ gh repo license view MIT

# View the MIT license from license key
$ gh repo license view mit

# View the GNU AGPL-3.0 license from SPDX ID
$ gh repo license view AGPL-3.0

# View the GNU AGPL-3.0 license from license key
$ gh repo license view agpl-3.0

# Create a LICENSE.md with the MIT license
$ gh repo license view MIT > LICENSE.md
```

---

## gh repo autolink create

**URL:** https://cli.github.com/manual/gh_repo_autolink_create

**Contents:**
- gh repo autolink create
  - Options
  - Options inherited from parent commands
  - ALIASES
  - Examples
  - See also

Create a new autolink reference for a repository.

The keyPrefix argument specifies the prefix that will generate a link when it is appended by certain characters.

The urlTemplate argument specifies the target URL that will be generated when the keyPrefix is found, which must contain <num> variable for the reference number.

By default, autolinks are alphanumeric with --numeric flag used to create a numeric autolink.

The <num> variable behavior differs depending on whether the autolink is alphanumeric or numeric:

If the template contains multiple instances of <num>, only the first will be replaced.

**Examples:**

Example 1 (unknown):
```unknown
gh repo autolink create <keyPrefix> <urlTemplate> [flags]
```

Example 2 (bash):
```bash
# Create an alphanumeric autolink to example.com for the key prefix "TICKET-".
# Generates https://example.com/TICKET?query=123abc from "TICKET-123abc".
$ gh repo autolink create TICKET- "https://example.com/TICKET?query=<num>"

# Create a numeric autolink to example.com for the key prefix "STORY-".
# Generates https://example.com/STORY?id=123 from "STORY-123".
$ gh repo autolink create STORY- "https://example.com/STORY?id=<num>" --numeric
```

---

## gh repo fork

**URL:** https://cli.github.com/manual/gh_repo_fork

**Contents:**
- gh repo fork
  - Options
  - See also
  - In use
    - With no arguments
    - With arguments
    - Using flags

Create a fork of a repository.

With no argument, creates a fork of the current repository. Otherwise, forks the specified repository.

By default, the new fork is set to be your origin remote and any existing origin remote is renamed to upstream. To alter this behavior, you can set a name for the new fork's remote with --remote-name.

The upstream remote will be set as the default remote repository.

Additional git clone flags can be passed after --.

Inside a git reposi

# Gh-Cli - Search

**Pages:** 7

---

## gh search prs

**URL:** https://cli.github.com/manual/gh_search_prs

**Contents:**
- gh search prs
  - Options
  - JSON Fields
  - Examples
  - See also

Search for pull requests on GitHub.

The command supports constructing queries using the GitHub search syntax, using the parameter and qualifier flags, or a combination of the two.

GitHub search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests

On supported GitHub hosts, advanced issue search syntax can be used in the --search query. For more information about advanced issue search, see: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues

For more information on handling search queries containing a hyphen, run gh search --help.

assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, isDraft, isLocked, isPullRequest, labels, number, repository, state, title, updatedAt, url

**Examples:**

Example 1 (unknown):
```unknown
gh search prs [<query>] [flags]
```

Example 2 (bash):
```bash
# Search pull requests matching set of keywords "fix" and "bug"
$ gh search prs fix bug

# Search draft pull requests in cli repository
$ gh search prs --repo=cli/cli --draft

# Search open pull requests requesting your review
$ gh search prs --review-requested=@me --state=open

# Search merged pull requests assigned to yourself
$ gh search prs --assignee=@me --merged

# Search pull requests with numerous reactions
$ gh search prs --reactions=">100"

# Search pull requests without label "bug"
$ gh search prs -- -label:bug

# Search pull requests only from un-archived repositories (default is all repositories)
$ gh search prs --owner github --archived=false
```

---

## gh search issues

**URL:** https://cli.github.com/manual/gh_search_issues

**Contents:**
- gh search issues
  - Options
  - JSON Fields
  - Examples
  - See also

Search for issues on GitHub.

The command supports constructing queries using the GitHub search syntax, using the parameter and qualifier flags, or a combination of the two.

GitHub search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests

On supported GitHub hosts, advanced issue search syntax can be used in the --search query. For more information about advanced issue search, see: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues

For more information on handling search queries containing a hyphen, run gh search --help.

assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, isLocked, isPullRequest, labels, number, repository, state, title, updatedAt, url

**Examples:**

Example 1 (unknown):
```unknown
gh search issues [<query>] [flags]
```

Example 2 (bash):
```bash
# Search issues matching set of keywords "readme" and "typo"
$ gh search issues readme typo

# Search issues matching phrase "broken feature"
$ gh search issues "broken feature"

# Search issues and pull requests in cli organization
$ gh search issues --include-prs --owner=cli

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

# Search issues with numerous comments
$ gh search issues --comments=">100"

# Search issues without label "bug"
$ gh search issues -- -label:bug

# Search issues only from un-archived repositories (default is all repositories)
$ gh search issues --owner github --archived=false
```

---

## gh search code

**URL:** https://cli.github.com/manual/gh_search_code

**Contents:**
- gh search code
  - Options
  - JSON Fields
  - Examples
  - See also

Search within code in GitHub repositories.

The search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-code

Note that these search results are powered by what is now a legacy GitHub code search engine. The results might not match what is seen on github.com, and new features like regex search are not yet available via the GitHub API.

For more information on handling search queries containing a hyphen, run gh search --help.

path, repository, sha, textMatches, url

**Examples:**

Example 1 (unknown):
```unknown
gh search code <query> [flags]
```

Example 2 (bash):
```bash
# Search code matching "react" and "lifecycle"
$ gh search code react lifecycle

# Search code matching "error handling"
$ gh search code "error handling"

# Search code matching "deque" in Python files
$ gh search code deque --language=python

# Search code matching "cli" in repositories owned by microsoft organization
$ gh search code cli --owner=microsoft

# Search code matching "panic" in the GitHub CLI repository
$ gh search code panic --repo cli/cli

# Search code matching keyword "lint" in package.json files
$ gh search code lint --filename package.json
```

---

## gh search commits

**URL:** https://cli.github.com/manual/gh_search_commits

**Contents:**
- gh search commits
  - Options
  - JSON Fields
  - Examples
  - See also

Search for commits on GitHub.

The command supports constructing queries using the GitHub search syntax, using the parameter and qualifier flags, or a combination of the two.

GitHub search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-commits

For more information on handling search queries containing a hyphen, run gh search --help.

author, commit, committer, id, parents, repository, sha, url

**Examples:**

Example 1 (unknown):
```unknown
gh search commits [<query>] [flags]
```

Example 2 (bash):
```bash
# Search commits matching set of keywords "readme" and "typo"
$ gh search commits readme typo

# Search commits matching phrase "bug fix"
$ gh search commits "bug fix"

# Search commits committed by user "monalisa"
$ gh search commits --committer=monalisa

# Search commits authored by users with name "Jane Doe"
$ gh search commits --author-name="Jane Doe"

# Search commits matching hash "8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3"
$ gh search commits --hash=8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3

# Search commits authored before February 1st, 2022
$ gh search commits --author-date="<2022-02-01"
```

---

## gh extension search

**URL:** https://cli.github.com/manual/gh_extension_search

**Contents:**
- gh extension search
  - Options
  - JSON Fields
  - Examples
  - See also

Search for gh extensions.

With no arguments, this command prints out the first 30 extensions available to install sorted by number of stars. More extensions can be fetched by specifying a higher limit with the --limit flag.

When connected to a terminal, this command prints out three columns. The first has a ✓ if the extension is already installed locally. The second is the full name of the extension repository in OWNER/REPO format. The third is the extension's description.

When not connected to a terminal, the ✓ character is rendered as the word "installed" but otherwise the order and content of the columns are the same.

This command behaves similarly to gh search repos but does not support as many search qualifiers. For a finer grained search of extensions, try using:

and adding qualifiers as needed. See gh help search repos to learn more about repository search.

For listing just the extensions that are already installed locally, see:

createdAt, defaultBranch, description, forksCount, fullName, hasDownloads, hasIssues, hasPages, hasProjects, hasWiki, homepage, id, isArchived, isDisabled, isFork, isPrivate, language, license, name, openIssuesCount, owner, pushedAt, size, stargazersCount, updatedAt, url, visibility, watchersCount

**Examples:**

Example 1 (unknown):
```unknown
gh extension search [<query>] [flags]
```

Example 2 (unknown):
```unknown
gh search repos --topic "gh-extension"
```

Example 3 (unknown):
```unknown
gh ext list
```

Example 4 (bash):
```bash
# List the first 30 extensions sorted by star count, descending
$ gh ext search

# List more extensions
$ gh ext search --limit 300

# List extensions matching the term "branch"
$ gh ext search branch

# List extensions owned by organization "github"
$ gh ext search --owner github

# List extensions, sorting by recently updated, ascending
$ gh ext search --sort updated --order asc

# List extensions, filtering by license
$ gh ext search --license MIT

# Open search results in the browser
$ gh ext search -w
```

---

## gh search repos

**URL:** https://cli.github.com/manual/gh_search_repos

**Contents:**
- gh search repos
  - Options
  - JSON Fields
  - Examples
  - See also

Search for repositories on GitHub.

The command supports constructing queries using the GitHub search syntax, using the parameter and qualifier flags, or a combination of the two.

GitHub search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-for-repositories

For more information on handling search queries containing a hyphen, run gh search --help.

createdAt, defaultBranch, description, forksCount, fullName, hasDownloads, hasIssues, hasPages, hasProjects, hasWiki, homepage, id, isArchived, isDisabled, isFork, isPrivate, language, license, name, openIssuesCount, owner, pushedAt, size, stargazersCount, updatedAt, url, visibility, watchersCount

**Examples:**

Example 1 (unknown):
```unknown
gh search repos [<query>] [flags]
```

Example 2 (bash):
```bash
# Search repositories matching set of keywords "cli" and "shell"
$ gh search repos cli shell

# Search repositories matching phrase "vim plugin"
$ gh search repos "vim plugin"

# Search repositories public repos in the microsoft organization
$ gh search repos --owner=microsoft --visibility=public

# Search repositories with a set of topics
$ gh search repos --topic=unix,terminal

# Search repositories by coding language and number of good first issues
$ gh search repos --language=go --good-first-issues=">=10"

# Search repositories without topic "linux"
$ gh search repos -- -topic:linux

# Search repositories excluding archived repositories
$ gh search repos --archived=false
```

---

## gh search

**URL:** https://cli.github.com/manual/gh_search

**Contents:**
- gh search
  - Available commands
  - See also

Search across all of GitHub.

Excluding search results that match a qualifier

In a browser, the GitHub search syntax supports excluding results that match a search qualifier by prefixing the qualifier with a hyphen. For example, to search for issues that do not have the label "bug", you would use -label:bug as a search qualifier.

gh supports this syntax in gh search as well, but it requires extra command line arguments to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen.

On Unix-like systems, you can use the -- argument to indicate that the arguments that follow are not a flag, but rather a query string. For example:

$ gh search issues -- "my-search-query -label:bug"

On PowerShell, you must use both the --% argument and the -- argument to produce the same effect. For example:

$ gh --% search issues -- "my search query -label:bug"

See the following for more information:

---

## Gotchas

### `gh search prs` has no `mergedAt` field

The `search prs` field set is much narrower than `pr view`'s. `mergedAt` does not exist and hard-errors with `Unknown JSON field: "mergedAt"`. Use `closedAt` - a merged PR always has it set.

```bash
# ✅ Correct
gh search prs "is:merged" --json closedAt,title --limit 5

# ❌ Errors
gh search prs "is:merged" --json mergedAt
```

Run any command with a bare `--json` to print its valid field list.

### Write queries as keywords + qualifiers, not sentences

GitHub search is not semantic. A natural-language sentence returns near-nothing; use keywords plus qualifiers.

```bash
# ✅ Correct
gh search repos "rate limiting middleware language:go stars:>500"

# ❌ Returns almost nothing
gh search repos "what is the best go library for rate limiting middleware"
```

The search *type* (code vs repos vs issues) is never part of the query string - it is the subcommand.

### Date-scoped listing without paginating everything

`gh pr list` and `gh issue list` accept `--search` with qualifiers, which is the practical way to do incremental scans:

```bash
gh pr list --repo OWNER/REPO --search "updated:>2026-07-01" --state all
gh issue list --repo OWNER/REPO --search "updated:>2026-07-01 label:bug"
```

# 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:**

```bash
# ✅ 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:**

```bash
# ✅ 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

A negative qualifier (prefixed with `-`) inside a quoted query is fine as long as the query does not **begin** with the hyphen:

```bash
# ✅ Works without `--` - query starts with a word
gh search issues "bug report -label:wontfix"

# ❌ Fails - query starts with a hyphen, parsed as a flag
gh search issues "-label:wontfix bug"
# unknown shorthand flag: 'l' in -label:wontfix bug
```

### Use `--`, and put flags before it

`--` marks the end of flags, so a query starting with a hyphen is read as positional. **Everything after `--` is positional** - trailing flags are silently swallowed into the query string:

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

# ❌ Wrong - `--limit 5` becomes search text; returns the default 30 results
gh search issues -- "-label:wontfix bug" --limit 5
```

### PowerShell

Use `--%` (stop parsing) operator:

```bash
# ✅ 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

```bash
# 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

```bash
# ✅ 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

```bash
# 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:

```bash
# ✅ 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:

```bash
# ✅ 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

GitHub code search has **no `*` wildcard** - an asterisk is matched as a literal character. `gh search code "function*"` returns files containing the literal token `function*` (e.g. JS generator declarations), not every word starting with "function".

```bash
# ❌ Not a wildcard - matches the literal string "function*"
gh search code "function*" --language=typescript

# ✅ Scope with flags instead
gh search code "function" --language=typescript --filename hooks.ts
```

## JSON Output Quirks

### jq is required for field extraction

```bash
# ✅ 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

```bash
# ✅ 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

```bash
# ✅ 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

The Contents API returns file content base64-encoded. There is **no `base64decode` template function** in `gh` - `--template '{{.content | base64decode}}'` fails with `template: :1: function "base64decode" not defined`. The full function list is in `gh help formatting`.

```bash
# ✅ Best - purpose-built command, no decoding needed
gh repo read-file file.ts --repo owner/repo

# ✅ Ask the API for raw bytes
gh api repos/owner/repo/contents/file.ts -H "Accept: application/vnd.github.raw"

# ✅ Or decode the JSON response yourself
gh api repos/owner/repo/contents/file.ts --jq '.content' | base64 -d

# ❌ Wrong - no such template function
gh api repos/owner/repo/contents/file.ts --template '{{.content | base64decode}}'
```

The Contents API only inlines files up to **1MB**; past that, `.content` comes back empty. `gh repo read-file` falls back to raw fetching automatically, which is why it is the safer default.

### Recursive tree flag

For recursive directory listings, use query parameter:

```bash
# ✅ 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`:

```bash
# ✅ 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:

```bash
# 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

```bash
# 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:

```bash
# 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

Rate limits are **per-resource**, and search is far tighter than the core budget most people quote:

| Resource | Unauthenticated | Authenticated |
|----------|-----------------|---------------|
| `core` (`gh api`, `gh repo view`, `gh repo read-file`) | 60/hr | 5000/hr |
| `search` (repos, issues, prs, commits) | 10/min | 30/min |
| `code_search` | n/a | 10/min |
| `graphql` | n/a | 5000/hr |

```bash
# Check every resource's live limit and remaining budget
gh api rate_limit --jq '.resources | map_values({limit, remaining})'
```

A search-heavy loop exhausts the 30/min search budget long before it dents the 5000/hr core budget. Search also caps at **1000 total results** per query regardless of `--limit`.

## Quoting Rules

### Shell quoting

```bash
# ✅ 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

```bash
# ✅ 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 code has no sorting

`gh search code` is powered by GitHub's legacy code-search engine and supports **no** `--sort`/`--order` flags - passing them fails with `unknown flag: --sort`. A `stars:>N` (or similar repo-popularity) qualifier inside the query is matched as literal file text, not a filter. Scope results with the available flags instead:

```bash
# ✅ Available scoping flags
gh search code "useWallet" --language=typescript --owner=vercel
gh search code --filename Dockerfile --extension dockerfile
gh search code react --match path   # match file path vs file contents {file|path}

# ❌ Wrong - no such flag on code search
gh search code "useWallet" --sort indexed
gh search code "useWallet" --sort stars
```

`--sort`/`--order` *do* work on `gh search repos` ({forks|help-wanted-issues|stars|updated}) and `gh search issues`/`gh search prs` - it is only code search that dropped them.

### gh search vs gh api

Different approaches for different use cases:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# Check auth status
gh auth status

# Re-authenticate
gh auth login
```

## Tips

### Always test field names

Run the command with a bare `--json` to list the valid fields. Note it writes the list to **stderr** and exits non-zero, so piping it to `jq` yields nothing:

```bash
# ✅ Correct - prints the available field list
gh repo view owner/repo --json
gh search repos "query" --json

# ❌ Wrong - stdout is empty, jq prints nothing
gh repo view owner/repo --json | jq keys
```

An empty JSON result from `--json` usually means the command errored on an unknown field rather than matching nothing. Re-run it bare to see the error.

### Use --help

Every command has detailed help:

```bash
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