github-image-upload

---

gh-image drops a screenshot — or any GitHub-supported file like a PDF, zip, or log — into a bug report, README, or Slack thread without leaving the terminal, and uploads on private repos stay private. Images render as inline embeds, videos as inline players, and other files as download links.

$ gh image screenshot.png
![screenshot.png](https://github.com/user-attachments/assets/88f4599a-…-bc24)

$ gh image report.pdf
[report.pdf](https://github.com/user-attachments/files/123456/report.pdf)

[!NOTE] GitHub shipped first-party attachment support on 2026-09-01. To attach an image or video to an issue or PR on a repository you can push to, update to gh v2.99.0 or later and use --attach — for most people that is enough. It works on gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit and gh pr comment.

gh-image covers what that flag does not:

• Any file type GitHub accepts — PDFs, zips, logs, CSVs, source files. --attach takes nine image and video extensions.
• Repositories you can only read — attach a screenshot to a bug report on a project you do not have push access to.
• A link on its own — for a README, a commit message, a Slack thread, or anywhere that isn't an issue or PR.
• Fetching attachments back down — gh image download pulls a user-attachments file to disk.
• CI and automation — --attach rejects the Actions GITHUB_TOKEN, so a workflow cannot attach anything with it. gh image runs unattended with a session token (see CI / CD).

It also wraps --attach rather than competing with it: pass a gh command after -- and the eligible files go through gh itself. See Post it in one command.

Installation

gh extension install drogers0/gh-image

That's it. The gh CLI auto-detects your platform and downloads the prebuilt binary. Pre-built releases ship for macOS (arm64, amd64), Linux (amd64, arm64), Windows (amd64), and Android/Termux (arm64).

Release binaries are signed with build provenance attestations, which prove a binary was built by this repository's release workflow from a specific commit. To check one before installing, download it from the releases page and run:

gh attestation verify darwin-arm64 --owner drogers0

Note that gh extension install does not verify attestations itself — this is an explicit check for anyone who wants it.

git clone https://github.com/drogers0/gh-image
cd gh-image
go build -o gh-image
gh extension install .

Requires Go 1.26+.

The cookie backend defaults to kooky; go build -tags hbd uses hackbrowserdata instead. The hbd build pins a hackbrowserdata commit carrying the macOS securityd-dump gate and library log silencing until its next release; override either dep with go get <module>@<ref> or a go.mod replace.

An alternate build swaps the browser-cookie reader from kooky to hackbrowserdata for broader browser coverage (Arc, Vivaldi, Firefox WAL, …). It ships as separate hbd-<os>-<arch> release assets — gh extension install still gets the default kooky build. Download one and run it directly:

gh release download <tag> --repo drogers0/gh-image \
  --pattern hbd-darwin-arm64 --output gh-image --clobber   # pick your platform
chmod +x gh-image
./gh-image screenshot.png

Pre-releases need the explicit tag (gh won't treat them as latest). Verify provenance with gh attestation verify gh-image --owner drogers0, or build it yourself with -tags hbd (see Build from source).

Usage

# Upload an image (infers repo from the current git workspace)
gh image screenshot.png

# Upload multiple files at once (images or anything GitHub accepts)
gh image hero.png diagram.png chart.png

# Upload any GitHub-supported file (PDF, zip, log, …) — renders as a download link
gh image report.pdf

# Target a specific repository
gh image screenshot.png --repo owner/repo

Each successful upload prints a ready-to-paste reference on its own line — an inline embed for images, a bare URL for videos (which GitHub renders as an inline player), and a download link for other files:

![hero.png](https://github.com/user-attachments/assets/…)
https://github.com/user-attachments/assets/…
[report.pdf](https://github.com/user-attachments/files/…/report.pdf)

If any upload fails, the error is printed to stderr and the process exits non-zero — other files in the batch still upload.

Download

# Fetch attachments, named from the URL, into the current directory
gh image download <url>... [--output-dir <dir>] [--no-clobber]

# Or send a single attachment somewhere specific — `-` for stdout
gh image download <url> --output <file>

Existing files are overwritten unless --no-clobber is passed, which writes name.1, name.2 instead. As with upload, a failed URL is reported to stderr and the process exits non-zero — the rest of the batch still downloads.

Post it in one command

Anything after -- is a gh command, forwarded as written. The files upload first and their links land in the body:

gh image bug.png              -- issue comment 42 --body-file repro.md
gh image diagram.pdf          -- pr create --fill --body-file design.md
gh image before.png after.png -- issue create --title "Layout breaks under 600px" --body-file report.md

Point the body at the files on disk — ![before](./before.png) — and those references are repointed at the uploaded assets; a file the body never mentions is appended to the end. A filename beginning with a dash is written ./-name.png, since -- now starts the gh command.

For a l