Use gh repo to Inspect and Safely Manage GitHub Repositories

You will finish with a small, repeatable workflow for inspecting a GitHub repository, cloning it locally, and telling GitHub CLI which repository a directory should target. You will also know which commands merely read remote state and which ones create, rename, archive or delete it. The examples use GitHub CLI 2.87.3, installed here on 23 September 2026.

Allow about fifteen minutes. You need gh, Git, a GitHub account for private repositories or write operations, and network access for commands that contact GitHub. Run ordinary inspection commands as your normal user. Do not use sudo: it will not grant GitHub permission and can leave a clone owned by root.

1. Confirm the installed command

Start with the version and the top-level repository help. These are local, read-only checks:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh repo --help
Work with GitHub repositories.

The general form is gh repo <command> [flags]. The installed manpage groups commands into general operations such as create and list, and targeted operations such as clone, view, set-default, archive and delete. The binary may expose more subcommands than an older local manpage, so use gh repo --help when a command is missing from your notes.

Checkpoint: confirm that the version is the one you intend to use before copying examples into automation. Help output is version-specific and does not require a login.

2. Inspect a repository without changing it

Use an explicit OWNER/REPO argument when you are not already in a clone:

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

View this repository on GitHub: https://github.com/cli/cli/

The description and README are displayed in the terminal. The exact text changes as the repository changes, so treat the sample output as a shape, not a value to test literally. Without an argument, gh repo view uses the repository for the current directory. With --web, it opens the repository in a browser rather than printing the README.

For scripts, request named JSON fields instead of scraping the human-readable layout:

$ 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"}

JSON field names are validated by the command. --jq filters the JSON result, while --template formats it with a Go template. Keep the repository argument explicit in a script so the result does not depend on the directory from which the script happens to run.

3. List repositories with a deliberate scope

gh repo list lists repositories owned by a user or organisation. Its default maximum is 30, so set a smaller limit when you only need a quick check:

$ gh repo list OWNER --limit 5 --json nameWithOwner,isPrivate,updatedAt
NAME             IS PRIVATE  UPDATED
OWNER/example    false       2026-09-20T12:34:56Z

Replace OWNER with a GitHub user or organisation. The displayed columns depend on the installed version and requested fields. Add --fork or --source to narrow the result, --archived or --no-archived to control archived repositories, and --visibility public, private or internal when that distinction matters.

A common trap is assuming that an organisation query finds every fork owned by its members. The command only lists repositories owned by the supplied owner. Its --fork and --source filters do not cross that ownership boundary.

4. Clone into a new local directory

Clone a public repository to a directory that does not already contain work:

$ mkdir -p ~/src
$ gh repo clone cli/cli ~/src/cli
Cloning into '/home/you/src/cli'...
$ git -C ~/src/cli remote -v
origin  https://github.com/cli/cli.git (fetch)
origin  https://github.com/cli/cli.git (push)

The repository may also be written as a GitHub URL or SSH URL. If no protocol is supplied, gh uses the configured git_protocol; inspect it with gh config get git_protocol. Additional Git clone flags go after --, for example gh repo clone cli/cli ~/src/cli -- --depth=1.

Do not point this at a directory containing uncommitted work. A failed or interrupted clone is easy to remove, but deleting a directory containing your own files is not a recovery strategy. If you deliberately need a fresh retry, first confirm the exact target with pwd and ls -la, then remove only that disposable clone directory.

5. Set and verify the default repository

Inside a clone, set the default repository used by commands that need a target, such as pull requests, issues, releases and Actions:

$ cd ~/src/cli
$ gh repo set-default origin
✓ Set cli/cli as the default repository for the current directory
$ gh repo set-default --view
cli/cli

You can use OWNER/REPO instead of a remote name. The setting helps commands that otherwise infer a repository from the current directory. It does not control repository and environment secrets, so do not assume that changing this value changes where secret commands operate.

To undo this local choice, run:

$ gh repo set-default --unset
✓ Unset the default repository

Checkpoint: run gh repo set-default --view after changing directories or remotes. An empty result is safer than silently targeting the wrong project.

6. Create a repository only when the target is clear

Creating a remote repository changes GitHub state. Check the name, owner, visibility and source directory before running it. A non-interactive create needs one of --public, --private or --internal:

$ gh repo create OWNER/example --private --description "Short project description"
✓ Created repository OWNER/example on GitHub
https://github.com/OWNER/example

To create from an existing local repository, add --source PATH. The optional --push sends local commits to the new remote, and --clone clones the new repository locally. Leave both flags out during a first review if you have not checked the local branch and commit history.

If an interactive create is interrupted, inspect GitHub and your local directory before trying again. Do not assume that a network error means the remote was not created. There is no generic undo in this workflow; if the repository is genuinely unwanted, use the delete command only after checking its exact name and preserving anything needed from it.

7. Treat archive, rename and delete as maintenance actions

The repository command group includes operations that change remote state. Archive makes a repository read-only on GitHub, rename changes its identity and links, and delete is destructive. Read each command's own help immediately before use:

$ gh repo archive --help
$ gh repo rename --help
$ gh repo delete --help

Do not put these commands in an unattended script until you have checked their confirmation behaviour and any required flag in this installed release. For deletion in particular, stop and confirm the full OWNER/REPO value, export or back up anything you must retain, and understand the organisation's retention policy. A local clone is not a complete recovery copy of issues, pull requests, releases, settings or Actions configuration.

For a mistaken default repository, use gh repo set-default --unset. For an unwanted local clone, remove only that clone after verifying its path. Neither action reverses a remote archive, rename or deletion.