GH-REPO-READ-FILE(1)

✨ GH-REPO-READ-FILE(1) ✨

okay so this is a page from the GitHub CLI manual and bestie, it's a good one 💅

🌸 NAME 🌸

gh-repo-read-file — read a file from a repository (preview) 🫶

🦋 SYNOPSIS 🦋

gh repo read-file <path> [flags]

💖 DESCRIPTION 💖

So like, you know how you can read the contents of a file in a GitHub repository without cloning the whole thing first? Yeah. That's the entire vibe. No cap. 🔥

⚠️ heads up bestie: this command is in preview and subject to change without notice. iykyk 😭

By default the file is read from the default branch. Wanna peek at a specific branch, tag, or commit? Slap on the --ref flag and you're so good.

When you're in TTY mode, the content gets shown through your pager (cute, cozy, very main character). But when stdout is piped or redirected, the raw content is written directly — no pager, just bytes. And if you'd rather save the file to disk, that's what --output is for 🎀

Okay now for the important safety bit: by default the command refuses to output a file that contains terminal escape sequences, because those could manipulate your terminal. Yeah. Not the vibe. 🙈 If you really do want to read it anyway, pass --allow-escape-sequences.

💀 lowkey crucial: this check applies only to terminal and piped output. Writing to disk with --output always includes the raw bytes, exactly as if --allow-escape-sequences were given. so like, be aware of that fr fr.

🎀 OPTIONS 🎀

• --allow-escape-sequences — allow printing terminal escape sequences (the "i know what i'm doing" flag 💅)
• --clobber — overwrite the output path if it already exists
• -q, --jq <expression> — filter JSON output using a jq expression ✨
• --json <fields> — output JSON with the specified fields
• -o, --output <path> — write the file to a path instead of stdout
• --ref <string> — the branch, tag, or commit to read 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 🌈

here's the whole squad, no gatekeeping 👑

content, downloadUrl, encoding, gitSHA, gitUrl, htmlUrl, name, path, size, type, url

⭐ EXIT CODES ⭐

• 0: successful execution — slay 💖
• 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 🧚

# Read a file from the default branch
$ gh repo read-file README.md --repo cli/cli

# Read a file at a specific ref
$ gh repo read-file README.md --repo cli/cli --ref v2.50.0

# Save a file to disk
$ gh repo read-file README.md --repo cli/cli --output download/README.md

# Print selected fields as JSON
$ gh repo read-file README.md --repo cli/cli --json name,path,size,type

# Read a file that contains terminal escape sequences
$ gh repo read-file path/to/file --repo OWNER/REPO --allow-escape-sequences

🍓 SEE ALSO 🍓

gh-repo(1) — go read that one next, bestie 🫶

---

and that's the whole page!! GitHub CLI v2.102.0, dated Oct 2026 — mwah, go read some files 👑💜