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



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



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



DESCRIPTION
       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.



OPTIONS
       -q, --jq <expression>
              Filter JSON output using a jq expression


       --json <fields>
              Output JSON with the specified fields


       --ref <string>
              The branch, tag, or commit to list from


       -R, --repo <[HOST/]OWNER/REPO>
              Select another repository using the [HOST/]OWNER/REPO format


       -t, --template <string>
              Format JSON output using a Go template; see "gh help formatting"



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



EXIT CODES
       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.



EXAMPLE
       # 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




SEE ALSO
       gh-repo(1)

                                   Sep 2026                GH-REPO-READ-DIR(1)