---
name: "gh-repo-read-dir"
section: "1"
platform: "linux"
package: "github-cli"
version: "2.102.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gh-repo-read-dir"
---

# gh-repo-read-dir(1)

List a directory in a repository (preview)

## 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)](/gh-repo/1.md)**