GH-REPO-READ-DIR(1)

💅 GH-REPO-READ-DIR(1) — the GitHub CLI manual, bestie edition ✨

okay so this is gh-repo-read-dir, straight out of the GitHub CLI manual (v2.102.0, Oct 2026 — we'll get to that at the end 🎀).

---

🌸 NAME 🌸

gh-repo-read-dir — list a directory in a repository (preview, babes 👀)

---

✨ SYNOPSIS ✨

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

---

🦋 DESCRIPTION 🦋

So like… you wanna see what's inside a directory in a GitHub repository, but you do not wanna clone the whole thing first? Yeah. That's the entire point of this command. Iconic behavior, honestly.

Heads up bestie: this command is in preview and subject to change without notice. So don't get too attached to the exact shape of things, mwah 💋

By default, the directory gets listed from the default branch. Wanna peek at a specific branch, tag, or commit? That's what the --ref flag is for, slay. And if you don't give it any path at all? No worries — it just lists the repository root. Easy. 🫶

---

👑 OPTIONS 👑

• -q, --jq <expression> — filter the JSON output using a jq expression. Yes, the real jq. Go off. 🔥
• --json <fields> — output JSON with the specified fields (pick from the JSON FIELDS list below, iykyk).
• --ref <string> — the branch, tag, or commit to list from. Time-travel privileges ✨
• -R, --repo <[HOST/]OWNER/REPO> — select another repository using the [HOST/]OWNER/REPO format. Like, go look at someone else's repo, respectfully 💅
• -t, --template <string> — format the JSON output using a Go template; see gh help formatting for the deets.

---

🍓 JSON FIELDS 🍓

Here's the full roster of fields you can ask for, in this exact order:

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

---

🌈 EXIT CODES 🌈

• 0: Successful execution — we ate 💖
• 1: Error — it's giving hiccup 😭
• 2: Command canceled — you hit Ctrl+C, no judgment
• 4: Authentication required — log in first, bestie 🙈

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information. (read: check the help, there might be more lore 📖)

---

⭐ EXAMPLE ⭐

okay here's where it gets fun, look at these:

# 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

Like?? No clone, no fuss, just vibes and directory contents. Main character energy fr fr 💅✨

---

🧚 SEE ALSO 🧚

• gh-repo(1) — the whole repo family, go say hi 👋

---

and that's the whole page, bestie!! 🎀 this was GitHub CLI v2.102.0, dated Oct 2026 — screenshot it, cite it, live your truth. bye 💜🦋