GH-REPO-READ-DIR(1) GitHub CLI manual GH-REPO-READ-DIR(1)

gh-repo-read-dir - List a directory in a repository (preview)

gh repo read-dir [<path>] [flags]

List the contents of a directory in a GitHub repository without cloning it.

This command is in preview and subject to change without notice.

By default, the directory is listed from the default branch. Use the --ref flag to list from a specific branch, tag, or commit. When no path is given, the repository root is listed.

Filter JSON output using a jq expression
Output JSON with the specified fields
The branch, tag, or commit to list from
Select another repository using the [HOST/]OWNER/REPO format
Format JSON output using a Go template; see "gh help formatting"

gitSHA, gitType, mode, modeOctal, name, nameRaw, path, pathRaw, size, submodule, type

0: Successful execution

1: Error

2: Command canceled

4: Authentication required

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information.

# List the root of the default branch
$ gh repo read-dir --repo cli/cli
# List a subdirectory
$ gh repo read-dir docs --repo cli/cli
# List a directory at a specific ref
$ gh repo read-dir docs --repo cli/cli --ref v2.50.0
# Print selected fields as JSON
$ gh repo read-dir docs --repo cli/cli --json name,path,type,size

gh-repo(1)

Jun 2026