GitHub CLI: Media in issues, pull requests, and comments 🚀

[ebndev]

GitHub CLI now has a repeatable --attach flag that uploads a local image or video and references it inline in an issue, pull request, or comment body.

This is now generally available to all users on GitHub across all plans. You just need to update gh to v2.99.0.

Why this matters

Some things are easier to show than to describe (i.e., a UI bug, a rendered result, an error on screen). Previously, gh only wrote text, so adding an image or video to an issue or pull request meant stopping to open the browser, drag the file into the comment box, and copy the result back. Now, gh can attach images and videos directly from the command line.

--attach puts the image in the same command that writes Markdown. File the bug, and the screenshot lands with it, so the issue shows the actual problem the first time. Open the pull request with a before and after, and the reviewer sees the change instead of pulling the branch to check. Your coding agents get this too, so they can show a result rather than describe it.

Capabilities

• Attach from commands that write Markdown text: --attach is repeatable and works on gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, and gh pr comment.
• Keep your Markdown as written: A local path already referenced in the body is rewritten in place, so ![alt](./login.png) keeps its alt text and becomes the uploaded asset. Anything attached but never referenced is appended at the end.
• Post images and video: PNG, JPEG, GIF, WebP, SVG, MP4, MOV, and WebM are all supported.
• Describe what you attach: Alt text follows the path after #, as in --attach './login.png#The login error state'. Omit it and gh falls back to the filename.

Security and access controls

Uploads authenticate with the common token types gh already uses, either the OAuth token from gh auth login or a classic personal access token. Write access to the repository you are attaching to is required for image uploading.

--attach is generally available to all users on GitHub across all plans, with no preview period. Size limits match the web upload flow: 10 MB for images and GIFs, 10 MB for video on Free plans, and 100 MB for video on paid plans. GitHub Enterprise Server is not supported in this release.

Getting started

Update gh to v2.99.0, then run gh issue comment <number> --attach ./screenshot.png. --attach works the same way on gh issue and gh pr create, edit, and comment. Run gh help <command> for the full flag reference.

Read the docs to learn more about attaching files from the command line.

🌟 Leave a comment!

Join the discussion and leave feedback in the comments below!

[maxdanilov]

When will gh 2.99 be added to brew repositories? brew update && brew upgrade gh still brings in 2.98.0

[maxdanilov]

2.99 is in brew now, all good.

[Blue101black]

Will this be supported via API as well?

[larryhudson]

Would be great to see this capability added to the GitHub MCP server too, so that Claude Code on the web can attach screenshots to pull requests etc. Claude Code on the web uses the GitHub MCP server rather than the gh cli.

[suzuki-shunsuke]

Uploads authenticate with the common token types gh already uses, either the OAuth token from gh auth login or a classic personal access token.

It would be great if user access tokens ghu_* are also supported.

https://github.com/cli/cli/blob/e63f6149ef34757aa1d54dfd2b9324b03a055d88/internal/attachments/client.go#L71-L76

// uploadTokenTypes lists the credentials that can attach a file.
var uploadTokenTypes = []gh.TokenType{
	gh.TokenTypeOAuth,
	gh.TokenTypePersonalAccess,
	gh.TokenTypeFineGrainedPAT,
}

Context:

I'm developing CLI to create user access tokens for secure local development, but unfortunately, we can't upload files using user access tokens.
https://github.com/suzuki-shunsuke/ghtkn

[suzuki-shunsuke]

I found the related issue, but this is not only the issue of GitHub CLI but also the issue of API.

• --attach cannot work for GitHub App installation tokens — the upload endpoint 404s them even with write access cli/cli#14309