Upload images from the terminal and get markdown-ready URLs for GitHub issues, PRs, and comments. Auto-detects the best backend. Built for AI agents and humans.

Why do I need this?

GitHub has no API for uploading images to issues, PRs, or comments. This has been requested since 2020 — 5+ years, no resolution. The gh CLI's --body only accepts text. AI agents can take screenshots but can't attach them. It's a gap you are bound to hit.

gitshot fixes this in one command.

Installation

Install for Humans

# Use directly with npx (zero install)
npx gitshot rick.gif

# Install globally
npm install -g gitshot

Install for Agents

Install the gitshot skill for Command Code, Claude Code, Cursor, Copilot, Codex, and 40+ other agents:

npx skills add vipulgupta2048/gitshot

Once installed, your agent automatically knows when and how to use gitshot — just ask it to "attach a screenshot to the PR" or "upload an image to the issue."

Install as GitHub CLI Extension

gh extension install vipulgupta2048/gitshot
gh shot rick.gif --pr 42

Usage

# Upload + comment on a PR (one command)
gitshot rick.gif --pr 42

# Upload + comment with a caption
gitshot rick.gif --pr 42 -m "Here's the fix"

# Auto-detect PR from current branch
gitshot rick.gif --pr

# Upload + comment on an issue
gitshot rick.gif --issue 10

# Upload + create a new issue
gitshot rick.gif --new-issue "Button is misaligned"

# Multiple images with caption
gitshot before.png after.png --pr 42 -m "Visual diff"

# Just upload, print markdown (no GitHub action)
gitshot rick.gif

# Raw URL only (for scripting)
gitshot --raw rick.gif

# JSON output (for agents/LLMs)
gitshot --json rick.gif
# → {"url":"https://...","markdown":"![...](...)","backend":"release"}

How It Works

If you have gh CLI authenticated, gitshot creates a dedicated public repo (<you>/gitshot-images) and uploads images as GitHub Release Assets. URLs are permanent, hosted on GitHub infrastructure, and render in any GitHub markdown context. The repo is auto-created on first use.

No gh? It falls back to catbox.moe — free, no signup, zero config.

Privacy notice: The gitshot-images repo is created as public by default, meaning uploaded images are accessible to anyone with the URL. Do not upload sensitive content (credentials, internal dashboards, private data) using the default release backend. Since May 2023, GitHub restricts access to images attached to private repos — but release assets on a public repo have no such protection. Use Cloudinary or imgbb with access controls for sensitive images. You are responsible for what you upload.

Backends

| Backend | Setup | Limits | Best for | |---------|-------|--------|----------| | github releases (default) | gh CLI authenticated | 2GB/file | Most reliable. Images on GitHub. | | catbox (fallback) | None | 200MB/file | No gh CLI, quick and dirty | | cloudinary | CLOUDINARY_URL env var | 25GB free | Production, CDN, transforms | | imgbb | IMGBB_API_KEY env var | 32MB/file | Simple free hosting |

Auto-detection order

1. --backend flag → use that
2. CLOUDINARY_URL env var → Cloudinary
3. IMGBB_API_KEY env var → imgbb
4. gh CLI authenticated → release (creates <you>/gitshot-images)
5. None of the above → catbox

Using Cloudinary

export CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
gitshot rick.gif

Get your free URL at cloudinary.com/console.

Using imgbb

export IMGBB_API_KEY=your_api_key
gitshot rick.gif

Get your free key at api.imgbb.com.

Using a specific repo

gitshot --repo myorg/my-images rick.gif

Comparison

| Feature | gitshot | gh-attach | GHPic | Manual upload | |---------|---------|-----------|-------|---------------| | Zero dependencies | Yes | Playwright | Raycast | N/A | | No browser needed | Yes | No | No | No | | Works over SSH | Yes | No | No | No | | Works in CI | Yes | No | No | No | | Cross-platform | Yes | Partial | macOS only | Yes | | Agent-friendly | Yes | No | No | No | | Multiple backends | 4 | 1 | 1 | Manual | | Status | Active | Archived | Active | N/A |

Background

GitHub has no public API for uploading images to issues, PRs, or comments. This has been requested since 2020 with no resolution. The upload endpoint requires browser session cookies — not OAuth tokens, not PATs. There is no programmatic way to do it. gitshot works around this using GitHub Release Assets, which are fully API-accessible.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Code and assests licened under MIT. Built by Vipul Gupta using Command Code.