gitshot — Upload Images to GitHub

When to Use This Skill

• User asks to "upload", "attach", or "embed" an image/screenshot to a GitHub PR or issue
• A workflow produces screenshots or images that need to go into a PR comment or issue body
• User asks for a "visual diff", "before/after", or "screenshot" in a PR
• User says "add image to PR", "attach screenshot to issue", or similar
• You have taken a screenshot and need to include it in GitHub markdown

Quick Reference

# Upload one image — returns markdown
npx gitshot screenshot.png
# → ![screenshot](https://github.com/user/gitshot-images/releases/download/_gitshot/screenshot-a1b2c3d4.png)

# Upload and comment on a PR (most common agent workflow)
npx gitshot screenshot.png | gh pr comment <PR_NUMBER> --body-file -

# Upload and create an issue with image
npx gitshot bug.png | gh issue create --title "Bug report" --body-file -

# Upload multiple images
npx gitshot before.png after.png

# Get raw URL only (for embedding in larger text)
npx gitshot --raw screenshot.png

# JSON output (structured, for programmatic use)
npx gitshot --json screenshot.png
# → {"url":"...","markdown":"![...](...)","filename":"...","backend":"release"}

How It Works

1. If

   gh

   CLI is authenticated (most common): Uploads to

   <user>/gitshot-images

   repo as a GitHub Release Asset. Creates the repo automatically on first use.
2. If no

   gh

   CLI: Falls back to catbox.moe (free, no signup).
3. Optional: Set

   CLOUDINARY_URL

   or

   IMGBB_API_KEY

   env vars for those backends.

Common Agent Workflows

Screenshot → PR Comment

# Take screenshot on macOS, upload, comment on PR
screencapture -x /tmp/shot.png
npx gitshot /tmp/shot.png | gh pr comment 42 --body-file -

Visual Diff in PR Description

BEFORE=$(npx gitshot --raw before.png)
AFTER=$(npx gitshot --raw after.png)
echo "## Visual Diff\n| Before | After |\n|--------|-------|\n| ![]($BEFORE) | ![]($AFTER) |" | gh pr comment 42 --body-file -

Upload Image and Get URL for Manual Embedding

URL=$(npx gitshot --raw diagram.png)
# Now use $URL anywhere in markdown text

Create Issue with Screenshot

BODY=$(npx gitshot bug.png)
gh issue create --title "UI Bug: Button misaligned" --body "$BODY"

Important Notes

• stdout contains ONLY the URL or markdown (pipe-safe)
• stderr contains status messages (backend name, progress)
• Exit code 0 = success, 1 = failure
• Supported formats: PNG, JPG, JPEG, GIF, SVG, WebP, BMP, ICO, TIFF, AVIF
• First run with release backend auto-creates

  <user>/gitshot-images

  repo (one-time)
• Privacy: The release backend uploads to a PUBLIC repo. Do not upload sensitive images (credentials, internal dashboards). Use Cloudinary or imgbb for sensitive content.