ghrepo - GitHub Repository Contents CLI

Prerequisites

• ghrepo binary in PATH (install via brew tap JsonLee12138/ghrepo && brew install ghrepo, or go install)
• A GitHub token set via GITHUB_TOKEN, GH_TOKEN, or --token flag
• For write/delete operations: token needs Contents: Read and Write scope

Quick Reference

ghrepo init <owner/repo>                                    # create AGENTS.md
ghrepo auth check                                          # verify token
ghrepo ls <owner/repo> <path> [--ref <ref>] [--recursive]  # list directory
ghrepo stat <owner/repo> <path> [--ref <ref>]               # file/dir metadata
ghrepo cat <owner/repo> <path> [--ref <ref>]                # output file content
ghrepo get <owner/repo> <path> --out <local> [--overwrite]  # download to local
ghrepo put <owner/repo> <path> -m <msg> --file <local> [-b <branch>] [-y] # create/update
ghrepo rm <owner/repo> <path> -m <msg> [-b <branch>] [-y]  # delete file

Global Flags

Commands

Initialize Project

ghrepo init owner/repo

Creates AGENTS.md in the current directory with the target repo and command reference. No token required. Fails if AGENTS.md already exists.

Read Operations

List directory:

ghrepo ls octocat/Hello-World src/
ghrepo ls octocat/Hello-World src/ --recursive --json

Read file to stdout:

ghrepo cat octocat/Hello-World README.md
ghrepo cat octocat/Hello-World README.md --ref v1.0 > local.md

Get metadata:

ghrepo stat octocat/Hello-World README.md --json

Download files/directories:

ghrepo get octocat/Hello-World README.md --out ./README.md
ghrepo get octocat/Hello-World docs/ --out ./local-docs --overwrite

Write Operations (require confirmation)

Create or update a file:

# From local file (interactive confirmation)
ghrepo put owner/repo path/to/file.txt -m "add file" --file ./local.txt

# From stdin (requires --yes since stdin is consumed)
echo "content" | ghrepo put owner/repo file.txt -m "create" --stdin --yes

# Skip confirmation + specify branch
ghrepo put owner/repo config.yml -m "update" --file ./config.yml -b develop --yes

Delete a file:

ghrepo rm owner/repo old-file.txt -m "remove file"
ghrepo rm owner/repo old-file.txt -m "cleanup" -b main --yes

Auth

ghrepo auth check
ghrepo auth check --json

Exit Codes

Key Behaviors

• put auto-detects create vs update (no need to specify SHA)
• put and rm show confirmation prompt by default; use --yes/-y to skip
• put requires exactly one of --file or --stdin for content source
• put and rm require -m/--message for commit message
• --ref works on all read commands (branch, tag, or SHA)
• get preserves directory structure when downloading folders
• All commands respect --json for machine-readable output

For detailed usage docs, see references/commands.md.