Skip to content

[Design] gh issue artifact edit #14526

Open
Open
[Design] gh issue artifact edit#14526
Labels
enhancementa request to improve CLIgh-issuerelating to the gh issue command

Description

@BagToad
BagToad
opened on Sep 25, 2026

gh issue artifact edit

Table of Contents

help

Category Scenario
Help edit

gh issue artifact edit

Category Scenario
Content From a file
Links From a .url file
Attachments With --attach
Content With --name
Content By URL
Content From standard input
Attachments Only --attach
Errors Error: nothing to change
Links With a URL
Errors Error: text file for a link
Errors Error: .url file for a document
Errors Error: --attach on a link
Errors Error: --body with --body-file
Scripting Piped output
Versions With --restore-version
Versions --restore-version with nothing to restore
Errors Error: version not found
Errors Error: invalid version
Errors Error: --restore-version with --name
Scripting Piped output with --restore-version
Scripting Piped output with nothing to restore

help

What is changing
  • Help: Help for gh issue artifact edit

edit

Input:

$ gh issue artifact edit --help

Output:

Source & reproduction 
printf 'Rename an issue artifact or replace its content. The type never changes, so a
link'\''s new content must be an http(s) URL or a `.url` Internet Shortcut file.

Name the artifact by its issue and number, or by its URL. `<issue>` is an
issue number or URL.

With only `--attach`, the attachments are appended to the current content.

With `--restore-version`, an earlier version'\''s name and content are saved as a
new version. `gh issue artifact view` shows the edit history.


\033[0;1;39mUSAGE\033[0m
  gh issue artifact edit {<issue> <artifact-number> | <artifact-url>} [flags]

\033[0;1;39mFLAGS\033[0m
      --attach file              Attach an image or video file, in '\''<file>#<image alt text>'\'' format
  -b, --body string              New content; for a link, a URL
  -F, --body-file file           Read new content from file (use "-" to read from standard input)
      --name string              New name
      --restore-version number   Restore the version with this number from the edit history

\033[0;1;39mINHERITED FLAGS\033[0m
      --help                     Show help for command
  -R, --repo [HOST/]OWNER/REPO   Select another repository using the [HOST/]OWNER/REPO format

\033[0;1;39mEXAMPLES\033[0m
  # Rename an artifact
  $ gh issue artifact edit 142 2 --name '\''OAuth callback plan v2'\''

  # Replace a document'\''s content with a file
  $ gh issue artifact edit 142 2 --body-file 2-OAuth-callback-plan.md

  # Point a link at a new URL
  $ gh issue artifact edit 142 3 --body https://github.com/monalisa/monas-cafe/wiki/OAuth-runbook-v2

  # Append a screenshot to a document
  $ gh issue artifact edit 142 2 --attach ./signin-flow.png

  # Restore an earlier version
  $ gh issue artifact edit 142 2 --restore-version 5

\033[0;1;39mLEARN MORE\033[0m
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual
  Learn about exit codes using `gh help exit-codes`
  Learn about accessibility experiences using `gh help accessibility`
' > help-edit.ans
freeze help-edit.ans --output help-edit.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1560

gh issue artifact edit

What is changing
  • Content: Replace an artifact's body with a file's contents
  • Links: Update a link artifact from a .url file
  • Attachments: --attach also works when editing, and appends unreferenced attachments
  • Content: Rename an artifact with --name, keeping its body
  • Content: An artifact URL can replace the issue and number
  • Content: Replace an artifact's body from standard input
  • Attachments: --attach on its own appends to the artifact's current body
  • Errors: Editing needs at least one of --name, --body, --body-file, --attach or --restore-version
  • Links: Update a link artifact's URL with --body
  • Errors: A link only takes an http(s) URL, from any source, or a .url file, so a text file is rejected
  • Errors: A .url file can only update a link
  • Errors: --attach can't be used with a link, because a link has no Markdown body
  • Errors: --body and --body-file are mutually exclusive
  • Scripting: When piped, edit prints one <status>\t<number>\t<name>\t<source>\t<reason> line, like create and delete
  • Versions: --restore-version saves an earlier version's name and body as a new version
  • Versions: When the current name and body already match the version, nothing is saved
  • Errors: A version the API didn't return fails before anything is saved
  • Errors: --restore-version must be at least 1
  • Errors: --restore-version can't be combined with --name, --body, --body-file or --attach
  • Scripting: When piped, a restore prints one restored line
  • Scripting: When piped, a restore with nothing to restore prints a skipped line with the reason

From a file

Input:

$ gh issue artifact edit 142 2 --body-file 2-OAuth-callback-plan.md

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-body-from-file.ans
freeze edit-body-from-file.ans --output edit-body-from-file.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2's body is exactly the contents of 2-OAuth-callback-plan.md
  • Artifact 2's number, name and type are unchanged

From a .url file

Input:

$ gh issue artifact edit 142 3 --body-file 3-Staging-OAuth-runbook.url

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:3}} ({{artifact_name:Staging OAuth runbook}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-link-from-url-file.ans
freeze edit-link-from-url-file.ans --output edit-link-from-url-file.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 3's body is the URL from the file's URL= line, not the file's raw text
  • Artifact 3 is still a link

With --attach

Input:

$ gh issue artifact edit 142 2 --body-file 2-OAuth-callback-plan.md --attach signin-flow.png

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-with-attach.ans
freeze edit-with-attach.ans --output edit-with-attach.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • References to ./signin-flow.png in the new body point to the uploaded asset, or it is appended when unreferenced

With --name

Input:

$ gh issue artifact edit 142 2 --name 'OAuth callback plan v2'

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan v2}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-rename.ans
freeze edit-rename.ans --output edit-rename.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is named "OAuth callback plan v2", and its body, number and type are unchanged

By URL

Input:

$ gh issue artifact edit https://github.com/monalisa/monas-cafe/issues/142/artifacts/2 --name 'OAuth callback plan v2'

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan v2}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-by-url.ans
freeze edit-by-url.ans --output edit-by-url.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is named "OAuth callback plan v2"

From standard input

Input:

$ cat signin-plan-v2.md | gh issue artifact edit 142 2 --body-file -

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-body-from-stdin.ans
freeze edit-body-from-stdin.ans --output edit-body-from-stdin.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2's body is exactly the piped content, and its name is unchanged

Only --attach

Input:

$ gh issue artifact edit 142 2 --attach signin-flow.png

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:2}} ({{artifact_name:OAuth callback plan}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-attach-only.ans
freeze edit-attach-only.ans --output edit-attach-only.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • The uploaded signin-flow.png is appended to artifact 2's existing body, and the rest of the body is unchanged

Error: nothing to change

Input:

$ gh issue artifact edit 142 2

Output:

Source & reproduction 
printf 'specify at least one of `--name`, `--body`, `--body-file`, `--attach`, or `--restore-version`
' > edit-error-nothing-to-change.ans
freeze edit-error-nothing-to-change.ans --output edit-error-nothing-to-change.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360

With a URL

Input:

$ gh issue artifact edit 142 3 --body https://github.com/monalisa/monas-cafe/wiki/OAuth-runbook-v2

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Updated artifact {{number:3}} ({{artifact_name:Staging OAuth runbook}}) on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-link-from-url.ans
freeze edit-link-from-url.ans --output edit-link-from-url.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects

Error: text file for a link

Input:

$ gh issue artifact edit 142 3 --body-file barista-notes.md

Output:

Source & reproduction 
printf 'artifact 3 is a link; its new content must be an http(s) URL or a .url file
' > edit-error-link-with-text.ans
freeze edit-error-link-with-text.ans --output edit-error-link-with-text.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 3 is unchanged

Error: .url file for a document

Input:

$ gh issue artifact edit 142 2 --body-file oauth-runbook.url

Output:

Source & reproduction 
printf 'artifact 2 is not a link; .url files can only update link artifacts
' > edit-error-url-file-for-document.ans
freeze edit-error-url-file-for-document.ans --output edit-error-url-file-for-document.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is unchanged

Error: --attach on a link

Input:

$ gh issue artifact edit 142 3 --attach signin-flow.png

Output:

Source & reproduction 
printf 'artifact 3 is a link; --attach can'\''t be used with link artifacts
' > edit-error-attach-on-link.ans
freeze edit-error-attach-on-link.ans --output edit-error-attach-on-link.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Nothing was uploaded, and artifact 3 is unchanged

Error: --body with --body-file

Input:

$ gh issue artifact edit 142 2 --body 'Text' --body-file signin-plan.md

Output:

Source & reproduction 
printf 'specify only one of `--body` or `--body-file`
' > edit-error-body-and-body-file.ans
freeze edit-error-body-and-body-file.ans --output edit-error-body-and-body-file.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360

Piped output

Input:

$ gh issue artifact edit 142 2 --name 'OAuth callback plan v2' | cat

Output:

Source & reproduction 
printf 'updated\t{{number:2}}\t{{artifact_name:OAuth callback plan v2}}\t\t
' > edit-piped.ans
freeze edit-piped.ans --output edit-piped.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is named "OAuth callback plan v2"

With --restore-version

Input:

$ gh issue artifact edit 142 2 --restore-version 5

Output:

Source & reproduction 
printf '\033[0;32m✓\033[0m Restored artifact {{number:2}} ({{artifact_name:OAuth plan}}) to version 5 on {{repo_ref:monalisa/monas-cafe#142}}
' > edit-restore-version.ans
freeze edit-restore-version.ans --output edit-restore-version.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is named "OAuth plan", and its body is version 5's body
  • Artifact 2 has 13 versions; version 13 has version 5's name and body, and versions 1 to 12 are unchanged

--restore-version with nothing to restore

Input:

$ gh issue artifact edit 142 2 --restore-version 12

Output:

Source & reproduction 
printf '\033[0;33m!\033[0m Artifact {{number:2}} ({{artifact_name:OAuth callback plan}}) on {{repo_ref:monalisa/monas-cafe#142}} already matches version 12
' > edit-restore-version-unchanged.ans
freeze edit-restore-version-unchanged.ans --output edit-restore-version-unchanged.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is unchanged, with 12 versions

Error: version not found

Input:

$ gh issue artifact edit 142 2 --restore-version 99

Output:

Source & reproduction 
printf 'version 99 not found for artifact 2
' > edit-error-restore-version-not-found.ans
freeze edit-error-restore-version-not-found.ans --output edit-error-restore-version-not-found.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is unchanged

Error: invalid version

Input:

$ gh issue artifact edit 142 2 --restore-version 0

Output:

Source & reproduction 
printf 'invalid version: 0
' > edit-error-invalid-restore-version.ans
freeze edit-error-invalid-restore-version.ans --output edit-error-invalid-restore-version.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360

Error: --restore-version with --name

Input:

$ gh issue artifact edit 142 2 --restore-version 5 --name 'OAuth plan v2'

Output:

Source & reproduction 
printf 'the `--restore-version` flag is not supported with `--name`, `--body`, `--body-file`, or `--attach`
' > edit-error-restore-version-with-name.ans
freeze edit-error-restore-version-with-name.ans --output edit-error-restore-version-with-name.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is unchanged

Piped output with --restore-version

Input:

$ gh issue artifact edit 142 2 --restore-version 5 | cat

Output:

Source & reproduction 
printf 'restored\t{{number:2}}\t{{artifact_name:OAuth plan}}\t\t
' > edit-restore-version-piped.ans
freeze edit-restore-version-piped.ans --output edit-restore-version-piped.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is named "OAuth plan", and its body is version 5's body

Piped output with nothing to restore

Input:

$ gh issue artifact edit 142 2 --restore-version 12 | cat

Output:

Source & reproduction 
printf 'skipped\t{{number:2}}\t{{artifact_name:OAuth callback plan}}\t\talready matches version 12
' > edit-restore-version-unchanged-piped.ans
freeze edit-restore-version-unchanged-piped.ans --output edit-restore-version-unchanged-piped.png --language ansi --font.family 'JetBrains Mono,SF Mono,Menlo,monospace' --font.size 12 --line-height 1.4 --window --padding '20,40,20,20' --background '#2b3037' --margin 20 --shadow.blur 6 --border.radius 8 --width 1360
Expected effects
  • Artifact 2 is unchanged, with 12 versions

Activity

  1. BagToad
    added
    enhancementa request to improve CLI
    gh-issuerelating to the gh issue command
    on Sep 25, 2026

  2. github-actions commented on Sep 25, 2026

    @github-actions
    github-actionsbot
    on Sep 25, 2026 – with GitHub Actions · Hidden as off-topic
  3. github-actions
    added
    needs-triageneeds to be reviewed
    and removed
    needs-triageneeds to be reviewed
    on Sep 25, 2026

  4. cli-triage commented on Sep 25, 2026

    @cli-triage
    cli-triagebot
    on Sep 25, 2026 – with CLI Triage

    This is a well-specified design proposal for gh issue artifact edit, one of five sibling design docs (list #14523, create #14525, view #14524, delete #14527) for the new gh issue artifact command family — no duplicates found. It's clearly an enhancement (new functionality, not a bug report), and it already carries the correct enhancement and gh-issue labels, so I'm not suggesting any additional labels. The doc includes full scenario coverage (help text, edit flows for docs/links/attachments, and error cases), so it looks ready for engineering/design review as-is.

    Generated by Issue Triage (skills-driven) for #14526 · copilot · auto · 30.8 AIC · ⌖ 1.61 AIC · ⊞ 9.5K · ◷

  5. BagToad
    added a parent issue on Sep 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementa request to improve CLIgh-issuerelating to the gh issue command

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions