Spark
Sign In
Skill

Upload images and files to GitHub from command line

A GitHub CLI extension that uploads local images to GitHub's user-attachments service and returns Markdown-ready URLs for embedding in pull requests, issues

Get skill
Works with githubslackchromefirefoxsafari
drogers0
Own this? Claim it

Maintainer of this project? Claim this page to edit the listing.

31
Spark score
out of 100
Updated 28 days ago
Version 1.1.0
Add to Favorites

Why it matters

Enable developers to attach screenshots, logs, PDFs, and other files to GitHub issues, pull requests, and READMEs directly from the terminal without switching to the browser, maintaining repository-scoped privacy for uploads on private repos.

Outcomes

What it gets done

01

Upload images that render as inline embeds in GitHub markdown

02

Attach PDFs, zips, logs, and videos as download or player links

03

Authenticate using existing browser session cookies without token setup

04

Batch upload multiple files and pipe markdown references into issue or PR creation commands

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-gh-image | bash

Overview

Upload images to GitHub (gh-image)

`gh-image` is a `gh` CLI extension that replicates GitHub's internal image upload flow, allowing you to attach local screenshots and images to pull requests, issues, and comments from the terminal. Use this skill when you need to attach screenshots to PR descriptions or issue bodies from the terminal, embed local images into GitHub Markdown without opening a browser, or upload images in headless environments using the `GH_SESSION_TOKEN` environment variable.

What it does

gh-image is a gh CLI extension that replicates GitHub's internal image upload flow, allowing you to attach local screenshots and images to pull requests, issues, and comments from the terminal. It uploads a local image file to GitHub's user-attachments service and returns a ready-to-embed Markdown image line, providing the missing "attach a screenshot" capability for command-line workflows.

When to use - and when NOT to

Use this skill when you need to:

  • Attach screenshots to PR descriptions or issue bodies from the terminal
  • Embed local images into GitHub Markdown without opening a browser
  • Add images to pull request comments or issue threads
  • Upload images in headless environments using the GH_SESSION_TOKEN environment variable

When NOT to use: Do not use this skill if you lack write access to the target repository, or if your organization enforces SAML SSO and you have not authorized the session at https://github.com/orgs/<org>/sso. Avoid using your personal user_session cookie in shared environments; use a dedicated bot account instead.

Inputs and outputs

Inputs: An absolute path to a local image file, the target repository (owner/repo format), and a GitHub user_session cookie (via --token flag, GH_SESSION_TOKEN environment variable, or browser cookie store).

Outputs: Markdown-formatted image reference printed to stdout, one line per image:

This output can be captured and embedded into PR bodies, issue descriptions, or comments using gh pr edit, gh issue edit, gh pr comment, or gh issue comment with the --body-file - flag.

Integrations

GitHub CLI (gh): Requires the gh CLI installed and authenticated. Install the extension with:

gh auth status                                   # gh installed & authenticated
gh extension list | grep -q 'drogers0/gh-image' \
  || gh extension install drogers0/gh-image      # review/pin the extension source first

Browser cookie stores: On local machines, gh-image automatically reads the user_session cookie from a logged-in browser (Chrome, Firefox, Safari, Edge). Windows + Chrome 127+ cannot read cookies due to a library limitation; use another browser or set GH_SESSION_TOKEN explicitly.

Headless environments: In headless contexts, set the GH_SESSION_TOKEN environment variable with a session cookie from a dedicated bot account.

Example workflow

Upload an image and append it to a pull request body:

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## Screenshots\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

Verify the image URL is present:

gh pr view <pr> --repo owner/repo --json body -q .body   # confirm URL present

For display sizing, embed an HTML tag instead of bare Markdown: " />.

Who it's for

This skill is designed for users who need to attach local image files to GitHub pull requests, issues, and comments from the terminal.

Limitations

Session cookie required: A user_session cookie grants full account access (not scoped like a personal access token) - treat it like a password and use a bot account in shared environments. Write access to the target repository is required. Private-repo images inherit repo visibility; anonymous fetches return 404/403 by design. The skill embeds the Markdown itself; gh-image only prints the URL.

Source README

Upload images to GitHub (gh-image)

GitHub has no public API for image uploads - the web UI uses an internal
endpoint that mints user-attachments URLs scoped to the repo's visibility.
gh-image (MIT, © drogers0) replicates
that flow as a gh CLI extension, so an agent can upload a local image from the
terminal and get a ready-to-embed Markdown image line back.

Overview

This skill drives gh-image to turn a local image file into a hosted GitHub
user-attachments URL, then embeds that URL into a pull request, issue, or
comment. It is the missing "attach a screenshot" capability for terminal agents.

When to Use This Skill

Use this skill when asked to:

  • "Attach a screenshot to the PR" or "add an image to the PR description"
  • "Put this image in the issue" / "comment with these screenshots"
  • "Show the test results / before-and-after in the PR"
  • Embed any local image into GitHub Markdown without leaving the terminal

How It Works

Step 1: Verify prerequisites

gh auth status                                   # gh installed & authenticated
gh extension list | grep -q 'drogers0/gh-image' \
  || gh extension install drogers0/gh-image      # review/pin the extension source first

gh-image does not use the gh token for the upload (that endpoint rejects
tokens). It needs a GitHub user_session cookie, resolved in this order:
--token <value> flag → GH_SESSION_TOKEN env var (use in CI/headless) → a
logged-in browser's cookie store (default for local use).

Step 2: Upload

### Use an absolute path; --repo is optional inside a repo working dir.
gh image "/abs/path/screenshot.png" --repo <owner>/<repo>

gh image prints Markdown to stdout, one line per image:

![screenshot.png](https://github.com/user-attachments/assets/<uuid>)

Capture that output - it is the embeddable reference.

Step 3: Embed into the PR / issue / comment

MD="$(gh image "/abs/path/shot.png" --repo owner/repo)"
BODY="$(gh pr view <pr> --repo owner/repo --json body -q .body)"
printf '%s\n\n## Screenshots\n\n%s\n' "$BODY" "$MD" \
  | gh pr edit <pr> --repo owner/repo --body-file -

Use gh pr comment, gh issue edit, or gh issue comment with --body-file -
for other targets. Always pass --body-file - (not inline --body) so multi-line
bodies and special characters can't break shell quoting.

Step 4: Verify

gh pr view <pr> --repo owner/repo --json body -q .body   # confirm URL present

Examples

  • Attach a CleanShot screenshot to PR #42: upload the file, append it under a
    ## Screenshots heading in the PR body.
  • Embed before/after images in a README: upload both, paste the two Markdown
    lines into the README at the relevant section.

Best Practices

  • Resolve globs to absolute paths first; quote paths with spaces/Unicode.
  • For display sizing, embed an HTML tag instead of bare Markdown:
    <img width="800" src="https://github.com/user-attachments/assets/<uuid>" />.
  • In CI, set GH_SESSION_TOKEN from a dedicated bot account.

Limitations

  • Session cookie required. A user_session cookie grants full account access
    (not scoped like a PAT) - treat it like a password; use a bot account in CI.
  • Write access to the target repo is required; orgs that enforce SAML SSO need
    the session authorized at https://github.com/orgs/<org>/sso first.
  • Private-repo images stay private: the user-attachments URL inherits repo
    visibility, so an anonymous fetch on a private repo returns 404/403 by design.
  • Windows + Chrome 127+ cannot read cookies (library limitation) - use another
    browser or GH_SESSION_TOKEN.
  • The skill embeds the Markdown itself; gh-image only prints the URL.

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.