List Your GitHub Gists Safely with gh gist list

You know you saved that snippet as a gist, but not what you called it or whether it was public. gh gist list shows your gists from the terminal, caps how many it fetches, and splits public from secret. It takes about five minutes.

• You need: the GitHub CLI, a shell, and an authenticated gh account with access to your gists.
• It is read-only. These commands do not create, edit or delete a gist.
• No elevated privileges.

1. Check the installed command

The command is a subcommand of gh, not a separate executable. Check which binary your shell will run and record its version:

$ command -v gh
/usr/bin/gh
$ gh version
gh version 2.87.3 (2026-02-23)

The examples were checked with GitHub CLI 2.87.3. The installed manual page is dated March 2026 and documents the basic list flags: --limit, --public and --secret. The command's current help also shows filtering options newer than that local manpage.

$ gh gist list --help

2. Confirm authentication first

A list belongs to a GitHub account, so an unauthenticated or wrongly selected account is the most common reason for an empty or failed result. Check the account and token state without changing it:

$ gh auth status

Look for the GitHub host and account you expect. The exact status text varies with the CLI version and login method.

When more than one account or host is configured, the selected host matters. A successful login to one GitHub host does not make gists on another host appear.

3. List recent entries with a small limit

Start with the default list. The manpage defines a default limit of 10, and gh gist list displays the entries in a table meant for interactive use:

$ gh gist list
ID              DESCRIPTION             FILES  VISIBILITY  UPDATED
0123456789ab    shell notes             1      secret      2026-09-20
abcdef012345    release checklist       2      public      2026-09-18

Your identifiers, descriptions and dates will differ. The useful result is a row for each gist GitHub returns, not a fixed table layout you should parse forever. For a quick check, make the request smaller:

$ gh gist list --limit 3
$ printf 'exit status: %s\n' "$?"
exit status: 0

-L 3 is the documented short form. The value is the maximum number of gists to fetch, not a promise that three rows exist. Fewer rows are normal if the account has fewer accessible gists, and an empty success can simply mean the account has none.

4. Separate public and secret gists

Use one visibility switch at a time for a focused review. This requests only public gists:

$ gh gist list --public --limit 10

Use --secret to request only secret gists:

$ gh gist list --secret --limit 10

If you pass both --public and --secret, do not rely on the result as a meaningful filter, because they express opposing selections. Use a single flag for an unambiguous command, and check the exit status if you are scripting it.

5. Build a repeatable inspection command

For a small manual review, this is a clear starting point:

$ gh gist list --limit 20 --public
$ gh gist list --limit 20 --secret

Run the two commands separately so the visibility boundary shows in your shell history. If you need more than 20 entries, raise the limit deliberately. A large request takes longer and puts more account metadata on screen.

6. Diagnose an empty or failed list

Repeat the read-only checks in this order:

1. Binary. Run gh version and confirm which binary is installed.
2. Account. Run gh auth status and confirm the intended account and host.
3. Unfiltered list. Run gh gist list --limit 1 without a visibility flag.
4. Focused list. Run one focused command, such as gh gist list --public --limit 1.

If the unfiltered command works but a focused one returns no rows, that may just be the account's visibility mix. If authentication fails, use the CLI's normal login or account-switching procedure rather than putting credentials on the command line. If GitHub reports a network or API error, retry after checking connectivity and the selected host.