Attaching files with GitHub CLI

Attach local images and videos to issues, pull requests, and comments without leaving the command line.

In this article

You can attach a local image or video from the command line with GitHub CLI using the --attach flag. GitHub CLI uploads the file to GitHub and writes the resulting URL into the body of your issue, pull request, or comment, so it renders inline just as it would if you attached it in your browser.

You need push access to the repository to attach files.

The --attach flag is available on the following commands:

  • gh issue create
  • gh issue edit
  • gh issue comment
  • gh pr create
  • gh pr edit
  • gh pr comment

Attaching a file

Pass --attach with the path to a local file. In the following example, replace ISSUE-NUMBER with the number of your issue and PATH/TO/IMAGE with the path to your image. You can repeat the flag to attach more than one file, but you can't attach the same file twice.

gh issue comment ISSUE-NUMBER --attach PATH/TO/IMAGE

You can combine --attach with --body or --body-file to embed images and videos in your Markdown. The following example uses placeholders for the pull request title, Markdown body file, and two image files.

gh pr create \
  --title "PULL-REQUEST-TITLE" \
  --body-file PATH/TO/BODY-FILE \
  --attach PATH/TO/FIRST-IMAGE \
  --attach PATH/TO/SECOND-IMAGE

To set alt text for an image, add it to the end of the path after a #, in place of ALT-TEXT.

gh issue comment ISSUE-NUMBER --attach 'PATH/TO/IMAGE#ALT-TEXT'

If you do not provide alt text, GitHub CLI uses the file name.

Note

Alt text is not supported on video files.

Embedding an attachment in Markdown

If your Markdown text already references a local file, and you attach that same file with --attach, GitHub CLI rewrites the reference in place to point at the uploaded file, rather than appending a second copy at the end. This lets you write Markdown with ordinary local paths, preview it locally where the images render, then post it unchanged. The reference is rewritten no matter where the body text comes from: --body, --body-file, standard input, or the text editor.

Embedding an image

For example, save the following content in PATH/TO/BODY-FILE:

The sign-in screen shows an error where the form should be:

![the sign-in screen showing an authentication error](PATH/TO/IMAGE)

Run the following command with --body-file:

gh issue comment \
  ISSUE-NUMBER \
  --body-file PATH/TO/BODY-FILE \
  --attach PATH/TO/IMAGE

GitHub CLI replaces the local path with the uploaded URL and keeps your Markdown and alt text. When a reference is rewritten, the alt text comes from the Markdown, so any # alt text on the flag applies only to files that are appended.

Any attached file that the body does not reference is appended to the end of the body, in the order you passed the flags.

Embedding a video

To embed a video as a player, save the following Markdown image reference in PATH/TO/VIDEO-BODY-FILE. The reference must be the only content in its paragraph.

![](PATH/TO/VIDEO)

Then attach the same video:

gh issue comment \
  ISSUE-NUMBER \
  --body-file PATH/TO/VIDEO-BODY-FILE \
  --attach PATH/TO/VIDEO

GitHub CLI replaces the entire reference with the uploaded URL, which renders as a player. If the reference appears within a sentence, it renders as a link instead.

Limitations

The GitHub CLI only supports uploading image and media files. For a list of supported file types, see Attaching files.