Back to Details

gitshot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

gitshot — Upload Images to GitHub

gitshot — 向GitHub上传图片

Upload images from terminal and get markdown-ready URLs for GitHub issues, PRs, and comments.
从终端上传图片，获取可直接用于GitHub Issue、PR和评论的Markdown格式URL。

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
  • 用户要求“上传”“附加”或“嵌入”图片/截图到GitHub PR或Issue
  • 工作流生成的截图或图片需要添加到PR评论或Issue正文中
  • 用户在PR中要求“视觉对比”“前后对比”或“截图”
  • 用户提出“向PR添加图片”“向Issue附加截图”等类似需求
  • 你已截取屏幕截图，需要将其包含在GitHub Markdown中

Quick Reference

快速参考

bash
undefined
bash
undefined

Upload one image — returns markdown

上传单张图片 — 返回Markdown格式

npx gitshot screenshot.png
npx gitshot screenshot.png

→ screenshot

→ screenshot

Upload and comment on a PR (most common agent workflow)

上传并在PR中添加评论（最常用的Agent工作流）

npx gitshot screenshot.png | gh pr comment <PR_NUMBER> --body-file -
npx gitshot screenshot.png | gh pr comment <PR_NUMBER> --body-file -

Upload and create an issue with image

上传图片并创建包含该图片的Issue

npx gitshot bug.png | gh issue create --title "Bug report" --body-file -
npx gitshot bug.png | gh issue create --title "Bug report" --body-file -

Upload multiple images

上传多张图片

npx gitshot before.png after.png
npx gitshot before.png after.png

Get raw URL only (for embedding in larger text)

仅获取原始URL（用于嵌入更长文本）

npx gitshot --raw screenshot.png
npx gitshot --raw screenshot.png

JSON output (structured, for programmatic use)

JSON格式输出（结构化，供程序化调用）

npx gitshot --json screenshot.png
npx gitshot --json screenshot.png

→ {"url":"...","markdown":"...","filename":"...","backend":"release"}

→ {"url":"...","markdown":"...","filename":"...","backend":"release"}

undefined
undefined

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.
  1. 若
    gh
    CLI已认证    （最常见情况）：将图片上传至
    <user>/gitshot-images
    仓库作为GitHub Release资产。首次使用时会自动创建该仓库。
  2. 若无
    gh
    CLI    ：回退至catbox.moe（免费，无需注册）。
  3. 可选配置：设置
    CLOUDINARY_URL
    或
    IMGBB_API_KEY
    环境变量以使用对应后端服务。

Common Agent Workflows

常用Agent工作流

Screenshot → PR Comment

截图 → PR评论

bash
undefined
bash
undefined

Take screenshot on macOS, upload, comment on PR

在macOS上截取屏幕，上传并在PR中添加评论

screencapture -x /tmp/shot.png npx gitshot /tmp/shot.png | gh pr comment 42 --body-file -
undefined
screencapture -x /tmp/shot.png npx gitshot /tmp/shot.png | gh pr comment 42 --body-file -
undefined

Visual Diff in PR Description

PR描述中的视觉对比

bash
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 -
bash
BEFORE=$(npx gitshot --raw before.png)
AFTER=$(npx gitshot --raw after.png)
echo "## 视觉对比\n| 之前 | 之后 |\n|--------|-------|\n| ![]($BEFORE) | ![]($AFTER) |" | gh pr comment 42 --body-file -

Upload Image and Get URL for Manual Embedding

上传图片并获取URL用于手动嵌入

bash
URL=$(npx gitshot --raw diagram.png)
bash
URL=$(npx gitshot --raw diagram.png)

Now use $URL anywhere in markdown text

现在可在任意Markdown文本中使用$URL

undefined
undefined

Create Issue with Screenshot

创建包含截图的Issue

bash
BODY=$(npx gitshot bug.png)
gh issue create --title "UI Bug: Button misaligned" --body "$BODY"
bash
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.
  • stdout仅包含URL或Markdown内容（支持管道传递）
  • stderr包含状态消息（后端名称、进度）
  • 退出码0表示成功，1表示失败
  • 支持格式：PNG、JPG、JPEG、GIF、SVG、WebP、BMP、ICO、TIFF、AVIF
  • 使用release后端首次运行时会自动创建
    <user>/gitshot-images
    仓库（仅一次）
  • 隐私提示：release后端会将图片上传至公开仓库。请勿上传敏感图片（如凭证、内部仪表盘）。敏感内容请使用Cloudinary或imgbb。