Inspect a GitHub Repository with gh repo view

You will finish with a repeatable way to inspect a GitHub repository from a Linux shell, switch the branch being viewed, open the repository in a browser, and request stable JSON for scripts. The examples use GitHub CLI 2.87.3, installed here as package gh.

Allow about ten minutes. You need gh, a working network connection and access to the repository you want to inspect. Public repositories are enough for the read-only examples. Authentication may still be required for a private repository. None of the commands below need sudo, and none change repository content or settings.

1. Confirm the installed command

Check the executable and version before relying on a flag. This is an ordinary, read-only command:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)

The relevant subcommand is gh repo view. Its basic form is gh repo view [REPOSITORY], where the repository can be written as OWNER/REPOSITORY. The installed manual also accepts no repository argument, in which case gh uses the repository for the current directory.

2. View a named repository

Start with a public repository whose name is explicit. This avoids an easy mistake: running the command from a directory that is not a Git checkout, or from the wrong checkout:

$ gh repo view cli/cli
GitHub's official command line tool

... repository description and README text ...

The exact display is repository content, so it will change. The command is intended to show the repository description and README. A successful result does not mean that the repository is suitable for every operation, nor does it clone anything locally.

Use the full owner and repository name when writing documentation, support notes or automation. A short name can be ambiguous outside the context of the current GitHub account.

3. Let the current checkout choose the repository

When you are already in a Git checkout with a GitHub remote, omit the repository argument:

$ cd /path/to/your/checkout
$ gh repo view

This convenience depends on the current directory and its Git remotes. Before trusting the result, inspect the remote without changing it:

$ git remote -v
origin  [email protected]:OWNER/REPOSITORY.git (fetch)
origin  [email protected]:OWNER/REPOSITORY.git (push)
$ gh repo view OWNER/REPOSITORY

Replace both placeholder values. If the checkout has several remotes, or its remote points at a mirror, the explicit form is easier to audit. If there is no repository for the current directory, use the error as a prompt to check the path and remote rather than adding sudo.

4. View a particular branch

Use --branch, or its short form -b, when the README or description on the default branch is not the one you need:

$ gh repo view cli/cli --branch trunk
... description and README for trunk ...

The branch must exist on the named repository. Branch names are data, so quote a value supplied by a variable or another command:

$ branch_name='trunk'
$ gh repo view cli/cli --branch "$branch_name"

5. Open the repository in a browser

Add --web, or -w, when the useful next step is reading the repository on GitHub rather than displaying it in the terminal:

$ gh repo view cli/cli --web

This asks the local environment to open the repository URL in its browser. On a headless server, a graphical browser may not be available and the command can fail even though the repository is valid. Use the terminal form or a text browser there. With a branch selected, include both options:

$ gh repo view cli/cli --branch trunk --web

Opening a page is not a repository mutation. Still, treat URLs and repository names supplied by untrusted input carefully. Do not pass an arbitrary string into a shell command without quoting and validating it.

6. Request fields as JSON

For scripts, do not scrape the human-oriented description and README output. Use --json with a comma-separated list of fields from the command's help:

$ gh repo view cli/cli --json nameWithOwner,description,url
{"description":"GitHub's official command line tool","nameWithOwner":"cli/cli","url":"https://github.com/cli/cli"}

Field selection is deliberate: it limits the data your script has to interpret and makes a later format change less disruptive. The available fields include repository metadata such as defaultBranchRef, isPrivate, licenseInfo, languages, pushedAt and visibility. Ask the installed help for the complete list on your machine.

Use --jq to filter the JSON with a jq expression:

$ gh repo view cli/cli --json nameWithOwner,description,url \
    --jq '.nameWithOwner + " | " + .description'
cli/cli | GitHub's official command line tool

For a Go template, use --template:

$ gh repo view cli/cli --json nameWithOwner,url \
    --template '{{.nameWithOwner}} -> {{.url}}{{"\n"}}'
cli/cli -> https://github.com/cli/cli

These formatting options apply to JSON output. Do not combine human-readable README scraping with a parser and then treat the result as an API contract.

7. Diagnose failures without changing anything

First separate lookup, authentication and network problems. Re-run the smallest safe query:

$ gh repo view cli/cli --json nameWithOwner --jq .nameWithOwner
cli/cli
$ printf 'exit status: %s\n' "$?"
exit status: 0

If a private repository fails while this public check works, authenticate with the normal GitHub CLI process and confirm that the account has access. If even the public check fails, inspect the network path and gh auth status; neither command changes repository data.

A non-zero status means the requested view was not produced. Do not pipe a failed command into a state-changing script without checking its status first. For example, in a shell script use set -o pipefail when a pipeline must fail if gh fails.