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]

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

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.

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.

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.

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.