Inspect a GitHub Project with gh project view

Use gh project view to see one GitHub Project from the terminal, as readable text, filtered JSON or a browser tab. The examples use GitHub CLI 2.87.3 from the gh package. Allow about ten minutes.

You need: GitHub CLI, an authenticated account, and access to the project.
It only reads. This guide reads project data or opens a page in your browser. It never creates, edits, closes or deletes a project.

1. Check the installed command

Confirm the binary and version first. These read-only commands need no elevated privileges:

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

Then read the local help. It helps when a script or guide was written for another release:

$ gh project view --help
View a project

USAGE
  gh project view [<number>] [flags]

Checkpoint: the command is gh project view, and the project number is optional in the syntax. Do not infer a project number from a repository number, because they are separate GitHub objects.

2. Confirm authentication first

Check the account and host without changing credentials:

$ gh auth status
github.com
  Logged in to github.com account YOUR_LOGIN
  Active account: true

The account name and status lines vary. If the command says your token lacks project access, follow the exact scope your CLI names. On this version, a read attempt without the required scope reports read:project and suggests:

$ gh auth refresh -s read:project

Warning: this refresh changes the stored authentication token, so treat it as security-sensitive. Review the host and account in gh auth status first. On a managed or shared workstation, check local policy before refreshing credentials. A successful refresh does not grant access to a project your GitHub account cannot see.

Tip: do not add sudo. GitHub CLI authentication and project permissions are user credentials, not local file permissions.

3. View a project you own

Pass the project number as a positional argument. Replace PROJECT_NUMBER with the number in the GitHub Project URL or interface:

$ gh project view PROJECT_NUMBER --owner '@me'

The --owner value makes the intended owner obvious in a script. The special value @me means the current user. When authentication and access are valid, the command prints the project's details. The human-readable fields and spacing are CLI output, not a stable interface for parsers.

For a first check, use a real number rather than the literal placeholder:

$ gh project view 1 --owner '@me'
Title: ...
Number: 1
URL: ...

Your values and layout will differ. Treat the example as a shape, not a promise that every project has the same fields. Check the shell status straight after the command:

$ printf 'exit status: %s\n' "$?"
exit status: 0

4. View a project owned by someone else

Use the login of the user or organisation that owns the project:

$ gh project view 1 --owner monalisa

Do not confuse the owner with a repository name. --owner takes a login, while the positional argument is the project number. A number that is valid for a different owner can still give a not-found or access error, because the owner is part of the lookup.

Tip: when a lookup fails, do not retry with several numbers. Check the owner and the token first. If the project is private, the authenticated account must be allowed to view it.

5. Request JSON for scripts

Use the documented JSON output when another program needs structured data:

$ gh project view 1 --owner '@me' --format json

Keep the raw JSON handy while you develop a script. The command also supports --jq for a jq expression and --template for a Go template. Both are output filters, not other ways to locate the project:

$ gh project view 1 --owner '@me' --format json --jq '.number'
$ gh project view 1 --owner '@me' --format json --template '{{.title}}\n'

Inspect first. The fields available to jq or a template depend on the JSON your CLI returns for that project. Look at the unfiltered result before writing a field-specific expression.
Empty output? Remove the filter and check the raw response before assuming the project is empty.
Quote expressions. Stop the shell interpreting braces, dollar signs and similar characters.

Warning: do not feed untrusted text into a template or jq expression without understanding how it will be parsed.

6. Open the project in a browser

Use --web when looking is quicker than reading terminal output:

$ gh project view 1 --owner monalisa --web

This asks the local environment to open the project in a browser. It does not edit the project. Over SSH or in a headless session the browser action may fail even though the API can reach the project. In that case, drop --web and use the terminal output or JSON mode.

Tip: do not use --web as a substitute for checking the owner. A browser opening the wrong project is still the wrong result.

7. Diagnose the usual failures

Missing-scope error. Refresh only the account and host you have just checked.
Authentication error. Run gh auth status and confirm the active account. Do not paste tokens into commands, issue reports or shell history.
Project not found. Check the number and owner together, then confirm the account can view the project in a browser. A not-found response can also be how an API hides a private project from an account without access.
JSON filter fails. Remove --jq or --template, request --format json, and inspect the actual response. If the unfiltered request fails, filtering cannot repair authentication or permission problems.
Script depends on a field. Keep a small fixture from a known response and test the expression against it. Do not parse the default human-readable display with line-oriented tools when JSON is available.

Done means

Version and syntax confirmed. You know the installed GitHub CLI version and the local gh project view syntax.
Account checked. You looked at the active account before diagnosing project access.
Number and owner deliberate. You supplied both, using @me where appropriate.
JSON before filters. You used --format json before applying jq or Go template filters in a script.
Browser mode understood. --web opens a page but does not change project data.
Nothing extra exposed. You did not grant extra access, change a project, or leak an authentication token.