.nh
.TH "GH-REPO-READ-DIR" "1" "Sep 2026" "" "GitHub CLI manual"

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


.SH SYNOPSIS
\fBgh repo read-dir [<path>] [flags]\fR


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

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

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


.SH OPTIONS
.TP
\fB-q\fR, \fB--jq\fR \fB<expression>\fR
Filter JSON output using a jq expression

.TP
\fB--json\fR \fB<fields>\fR
Output JSON with the specified fields

.TP
\fB--ref\fR \fB<string>\fR
The branch, tag, or commit to list from

.TP
\fB-R\fR, \fB--repo\fR \fB<[HOST/]OWNER/REPO>\fR
Select another repository using the [HOST/]OWNER/REPO format

.TP
\fB-t\fR, \fB--template\fR \fB<string>\fR
Format JSON output using a Go template; see "gh help formatting"


.SH JSON FIELDS
\fBgitSHA\fR, \fBgitType\fR, \fBmode\fR, \fBmodeOctal\fR, \fBname\fR, \fBnameRaw\fR, \fBpath\fR, \fBpathRaw\fR, \fBsize\fR, \fBsubmodule\fR, \fBtype\fR


.SH EXIT CODES
0: Successful execution

.PP
1: Error

.PP
2: Command canceled

.PP
4: Authentication required

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


.SH EXAMPLE
.EX
# 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

.EE


.SH SEE ALSO
\fBgh-repo(1)\fR