[Design] gh issue artifact list

`gh issue artifact list`

Category	Scenario
Terminal	List artifacts
Terminal	With an issue URL
Terminal	With `-R`
Terminal	With `--limit`
Scripting	Piped output
Terminal	No artifacts
Filtering	No artifacts match `--type`
Filtering	With `--type`
Filtering	With `--type generic`
Filtering	With `--type plan`
Errors	Error: unknown `--type`
Errors	Error: `--limit 0`
Errors	Error: a pull request
Errors	Error: host without artifacts
Errors	Error: GitHub Enterprise Server
JSON output	With `--json`

`help`

What is changing

Help: Help for gh issue artifact list

`list`

Input:

$ gh issue artifact list --help

Output:

Source & reproduction

printf 'List the artifacts on an issue, in number order. Every artifact is listed
unless you set `--limit`.

For more information about output formatting flags, see `gh help formatting`.

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

\033[0;1;39mALIASES\033[0m
  gh issue artifact ls

\033[0;1;39mFLAGS\033[0m
  -q, --jq expression     Filter JSON output using a jq expression
      --json fields       Output JSON with the specified fields
  -L, --limit int         Maximum number of artifacts to fetch
  -t, --template string   Format JSON output using a Go template; see "gh help formatting"
      --type string       Filter by type: {generic|plan|link}

\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;39mJSON FIELDS\033[0m
  body, bodyHtml, createdAt, creator, description, id, name, number, type,
  updatedAt, updatedByActor, url

\033[0;1;39mEXAMPLES\033[0m
  # List the artifacts on issue 142
  $ gh issue artifact list 142

  # List only links
  $ gh issue artifact list 142 --type link

  # Print artifact numbers and names as JSON
  $ gh issue artifact list 142 --json number,name

\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-list.ans
freeze help-list.ans --output help-list.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 list`

What is changing

Terminal: List every artifact on an issue as a table, in number order, with a header
Terminal: The issue argument can be a URL, which also names the repository
Terminal: -R selects the repository, like other gh commands
Terminal: --limit stops after N artifacts; the header still shows the total
Scripting: When piped, the same columns are tab-separated, with exact timestamps and no header row
Terminal: An issue with no artifacts prints a message to stderr in a terminal, and exits 0
Filtering: When a filter matches nothing, the message says so, and the command exits 0
Filtering: --type lists only artifacts of one type, filtered on the server
Filtering: --type generic also returns plans, which keep their plan type
Filtering: --type plan lists the same documents as --type generic, plans and generic artifacts alike
Errors: An unknown --type value lists the accepted values
Errors: --limit must be at least 1
Errors: Pull requests are rejected, whether given as a number or a URL
Errors: A host without artifact storage fails with the API's 503, as returned
Errors: GitHub Enterprise Server is refused before any request
JSON output: --json selects fields, with keys sorted like every gh --json command

List artifacts

Input:

$ gh issue artifact list 142

Output:

Source & reproduction

printf 'Showing {{count:3}} of {{count:3}} artifacts on {{repo_ref:monalisa/monas-cafe#142}}

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                  \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:2}}       {{artifact_name:OAuth callback plan}}     generic  \033[38;5;242m{{time_ago:about 2 hours ago}}\033[0m
{{number:3}}       {{artifact_name:Staging OAuth runbook}}   link     \033[38;5;242m{{time_ago:about 1 day ago}}\033[0m
{{number:5}}       {{artifact_name:Barista feedback notes}}  generic  \033[38;5;242m{{time_ago:about 3 days ago}}\033[0m
' > list-default.ans
freeze list-default.ans --output list-default.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 an issue URL

Input:

$ gh issue artifact list https://github.com/monalisa/monas-cafe/issues/142

Output:

Source & reproduction

printf 'Showing {{count:3}} of {{count:3}} artifacts on {{repo_ref:monalisa/monas-cafe#142}}

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                  \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:2}}       {{artifact_name:OAuth callback plan}}     generic  \033[38;5;242m{{time_ago:about 2 hours ago}}\033[0m
{{number:3}}       {{artifact_name:Staging OAuth runbook}}   link     \033[38;5;242m{{time_ago:about 1 day ago}}\033[0m
{{number:5}}       {{artifact_name:Barista feedback notes}}  generic  \033[38;5;242m{{time_ago:about 3 days ago}}\033[0m
' > list-issue-url.ans
freeze list-issue-url.ans --output list-issue-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

With `-R`

Input:

$ gh issue artifact list 142 -R monalisa/monas-cafe

Output:

Source & reproduction

printf 'Showing {{count:3}} of {{count:3}} artifacts on {{repo_ref:monalisa/monas-cafe#142}}

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                  \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:2}}       {{artifact_name:OAuth callback plan}}     generic  \033[38;5;242m{{time_ago:about 2 hours ago}}\033[0m
{{number:3}}       {{artifact_name:Staging OAuth runbook}}   link     \033[38;5;242m{{time_ago:about 1 day ago}}\033[0m
{{number:5}}       {{artifact_name:Barista feedback notes}}  generic  \033[38;5;242m{{time_ago:about 3 days ago}}\033[0m
' > list-repo-flag.ans
freeze list-repo-flag.ans --output list-repo-flag.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 `--limit`

Input:

$ gh issue artifact list 142 --limit 2

Output:

Source & reproduction

printf 'Showing {{count:2}} of {{count:3}} artifacts on {{repo_ref:monalisa/monas-cafe#142}}

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                 \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:2}}       {{artifact_name:OAuth callback plan}}    generic  \033[38;5;242m{{time_ago:about 2 hours ago}}\033[0m
{{number:3}}       {{artifact_name:Staging OAuth runbook}}  link     \033[38;5;242m{{time_ago:about 1 day ago}}\033[0m
' > list-limit.ans
freeze list-limit.ans --output list-limit.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 list 142 | cat

Output:

Source & reproduction

printf '{{number:2}}\t{{artifact_name:OAuth callback plan}}\tgeneric\t{{timestamp:2026-09-24T21:00:00Z}}
{{number:3}}\t{{artifact_name:Staging OAuth runbook}}\tlink\t{{timestamp:2026-09-23T23:00:00Z}}
{{number:5}}\t{{artifact_name:Barista feedback notes}}\tgeneric\t{{timestamp:2026-09-21T23:00:00Z}}
' > list-piped.ans
freeze list-piped.ans --output list-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

No artifacts

Input:

$ gh issue artifact list 161

Output:

Source & reproduction

printf 'no artifacts found on {{repo_ref:monalisa/monas-cafe#161}}
' > list-empty.ans
freeze list-empty.ans --output list-empty.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

No artifacts match `--type`

Input:

$ gh issue artifact list 128 --type generic

Output:

Source & reproduction

printf 'no artifacts match your search on {{repo_ref:monalisa/monas-cafe#128}}
' > list-empty-filtered.ans
freeze list-empty-filtered.ans --output list-empty-filtered.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 `--type`

Input:

$ gh issue artifact list 142 --type link

Output:

Source & reproduction

printf 'Showing {{count:1}} of {{count:1}} artifact on {{repo_ref:monalisa/monas-cafe#142}} that matches your search

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                 \033[0m  \033[2;4;37mTYPE\033[0m  \033[2;4;37mUPDATED        \033[0m
{{number:3}}       {{artifact_name:Staging OAuth runbook}}  link  \033[38;5;242m{{time_ago:about 1 day ago}}\033[0m
' > list-filter-type.ans
freeze list-filter-type.ans --output list-filter-type.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 `--type generic`

Input:

$ gh issue artifact list 137 --type generic

Output:

Source & reproduction

printf 'Showing {{count:2}} of {{count:2}} artifacts on {{repo_ref:monalisa/monas-cafe#137}} that match your search

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                   \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:1}}       {{artifact_name:Approved plan}}            plan     \033[38;5;242m{{time_ago:about 5 hours ago}}\033[0m
{{number:2}}       {{artifact_name:OAuth provider research}}  generic  \033[38;5;242m{{time_ago:about 1 hour ago}}\033[0m
' > list-filter-generic-includes-plans.ans
freeze list-filter-generic-includes-plans.ans --output list-filter-generic-includes-plans.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 `--type plan`

Input:

$ gh issue artifact list 137 --type plan

Output:

Source & reproduction

printf 'Showing {{count:2}} of {{count:2}} artifacts on {{repo_ref:monalisa/monas-cafe#137}} that match your search

\033[2;4;37mNUMBER\033[0m  \033[2;4;37mNAME                   \033[0m  \033[2;4;37mTYPE   \033[0m  \033[2;4;37mUPDATED          \033[0m
{{number:1}}       {{artifact_name:Approved plan}}            plan     \033[38;5;242m{{time_ago:about 5 hours ago}}\033[0m
{{number:2}}       {{artifact_name:OAuth provider research}}  generic  \033[38;5;242m{{time_ago:about 1 hour ago}}\033[0m
' > list-filter-plan-includes-generic.ans
freeze list-filter-plan-includes-generic.ans --output list-filter-plan-includes-generic.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: unknown `--type`

Input:

$ gh issue artifact list 142 --type docs

Output:

Source & reproduction

printf 'invalid argument "docs" for "--type" flag: valid values are {generic|plan|link}
' > list-error-invalid-type.ans
freeze list-error-invalid-type.ans --output list-error-invalid-type.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: `--limit 0`

Input:

$ gh issue artifact list 142 --limit 0

Output:

Source & reproduction

printf 'invalid limit: 0
' > list-error-invalid-limit.ans
freeze list-error-invalid-limit.ans --output list-error-invalid-limit.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: a pull request

Input:

$ gh issue artifact list 158

Output:

Source & reproduction

printf '{{repo_ref:monalisa/monas-cafe#158}} is a pull request; artifacts are only supported on issues
' > list-error-pull-request.ans
freeze list-error-pull-request.ans --output list-error-pull-request.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

No artifact request is made

Error: host without artifacts

Input:

$ gh issue artifact list 142

Output:

Source & reproduction

printf 'HTTP 503: Artifact storage is not available ({{url:https://api.monas-cafe.ghe.com/repos/monalisa/monas-cafe/issues/142/artifacts?per_page=100}})
' > list-error-storage-unavailable.ans
freeze list-error-storage-unavailable.ans --output list-error-storage-unavailable.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: GitHub Enterprise Server

Input:

$ gh issue artifact list 142

Output:

Source & reproduction

printf 'issue artifacts are not supported on GitHub Enterprise Server
' > list-error-enterprise-server.ans
freeze list-error-enterprise-server.ans --output list-error-enterprise-server.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

No request is made to the host

With `--json`

Input:

$ gh issue artifact list 142 --json number,name,type

Output:

Source & reproduction

printf '\033[1;37m[\033[0m
  \033[1;37m{\033[0m
    \033[1;34m"name"\033[1;37m:\033[0m \033[32m"{{artifact_name:OAuth callback plan}}"\033[1;37m,\033[0m
    \033[1;34m"number"\033[1;37m:\033[0m {{number:2}}\033[1;37m,\033[0m
    \033[1;34m"type"\033[1;37m:\033[0m \033[32m"generic"\033[0m
  \033[1;37m},\033[0m
  \033[1;37m{\033[0m
    \033[1;34m"name"\033[1;37m:\033[0m \033[32m"{{artifact_name:Staging OAuth runbook}}"\033[1;37m,\033[0m
    \033[1;34m"number"\033[1;37m:\033[0m {{number:3}}\033[1;37m,\033[0m
    \033[1;34m"type"\033[1;37m:\033[0m \033[32m"link"\033[0m
  \033[1;37m},\033[0m
  \033[1;37m{\033[0m
    \033[1;34m"name"\033[1;37m:\033[0m \033[32m"{{artifact_name:Barista feedback notes}}"\033[1;37m,\033[0m
    \033[1;34m"number"\033[1;37m:\033[0m {{number:5}}\033[1;37m,\033[0m
    \033[1;34m"type"\033[1;37m:\033[0m \033[32m"generic"\033[0m
  \033[1;37m}\033[0m
\033[1;37m]\033[0m
' > list-json.ans
freeze list-json.ans --output list-json.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

Thanks for filing this! This is a detailed design spec for a new gh issue artifact list subcommand (help text, terminal mockups, JSON output, and error scenarios), authored by a maintainer. It's already labeled enhancement and gh-issue, which look correct, so I'm not suggesting any additional labels. I checked for duplicates and didn't find an existing tracking issue for this exact command — it's a companion design to #14524 (gh issue artifact view), covering a different subcommand rather than overlapping with it.

Generated by Issue Triage (skills-driven) for #14523 · copilot · auto · 29.8 AIC · ⌖ 1.49 AIC · ⊞ 9.5K · ◷

Navigation Menu

Repository navigation

[Design] `gh issue artifact list` #14523

`gh issue artifact list`

Table of Contents

`help`

`gh issue artifact list`

`help`

`list`

`gh issue artifact list`

List artifacts

With an issue URL

With `-R`

With `--limit`

Piped output

No artifacts

No artifacts match `--type`

With `--type`

With `--type generic`

With `--type plan`

Error: unknown `--type`

Error: `--limit 0`

Error: a pull request

Error: host without artifacts

Error: GitHub Enterprise Server

With `--json`

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Design] gh issue artifact list #14523

Description

gh issue artifact list

Table of Contents

help

gh issue artifact list

help

list

gh issue artifact list

List artifacts

With an issue URL

With -R

With --limit

Piped output

No artifacts

No artifacts match --type

With --type

With --type generic

With --type plan

Error: unknown --type

Error: --limit 0

Error: a pull request

Error: host without artifacts

Error: GitHub Enterprise Server

With --json

Activity

github-actions commented on Sep 25, 2026

cli-triage commented on Sep 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[Design] `gh issue artifact list` #14523

`gh issue artifact list`

`help`

`gh issue artifact list`

`help`

`list`

`gh issue artifact list`

With `-R`

With `--limit`

No artifacts match `--type`

With `--type`

With `--type generic`

With `--type plan`

Error: unknown `--type`

Error: `--limit 0`

With `--json`