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

.SH NAME
gh-repo-read-file - Read a file from a repository (preview)


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


.SH DESCRIPTION
Read the contents of a file in a GitHub repository without cloning it.

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

.PP
By default, the file is read from the default branch. Use the \fB--ref\fR flag to
read from a specific branch, tag, or commit.

.PP
When run in TTY mode, the content is shown through your pager. When stdout is piped or
redirected, the raw content is written directly. To save the file to disk instead, use
the \fB--output\fR flag.

.PP
By default, the command refuses to output a file that contains terminal escape sequences,
since they could manipulate your terminal. Pass \fB--allow-escape-sequences\fR to read the file anyway.
This check applies only to terminal and piped output; writing to disk with \fB--output\fR always
includes the raw bytes, as if \fB--allow-escape-sequences\fR were given.


.SH OPTIONS
.TP
\fB--allow-escape-sequences\fR
Allow printing terminal escape sequences

.TP
\fB--clobber\fR
Overwrite the output path if it already exists

.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-o\fR, \fB--output\fR \fB<path>\fR
Write the file to a path instead of stdout

.TP
\fB--ref\fR \fB<string>\fR
The branch, tag, or commit to read 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
\fBcontent\fR, \fBdownloadUrl\fR, \fBencoding\fR, \fBgitSHA\fR, \fBgitUrl\fR, \fBhtmlUrl\fR, \fBname\fR, \fBpath\fR, \fBsize\fR, \fBtype\fR, \fBurl\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
# 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

.EE


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