List GitHub Gists Safely with gh gist list

You will finish with a read-only way to inspect the gists belonging to your GitHub account, restrict how many are fetched, and separate public entries from secret ones. Allow about five minutes. You need the GitHub CLI, a shell, and an authenticated gh account with access to your gists. These commands do not create, edit or delete a gist, and they do not require 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 here 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 that are newer than that local manpage. When a script must work across machines, check gh gist list --help on the target machine rather than assuming every installed release has the same flags.

$ gh gist list --help

2. Confirm authentication before fetching anything

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. If the command says that you are not logged in, stop there and authenticate through your normal organisation-approved process. Do not paste an access token into a shell command or into a gist description. Authentication changes are outside this listing workflow and may be security-sensitive.

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 automatically.

3. List the most 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 intended 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 returned by GitHub, not a fixed table layout that should be parsed 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. If the account has fewer than three accessible gists, fewer rows are normal. A successful empty result can also mean that the selected account has no gists.

4. Separate public and secret gists

Use one visibility switch at a time when you want a focused review. This command requests only public gists:

$ gh gist list --public --limit 10

Use --secret to request only secret gists:

$ gh gist list --secret --limit 10

Secret gists are not private in the same sense as repository access: anyone who has a secret gist's unguessable URL may be able to view it. Treat the output as sensitive because descriptions and identifiers can reveal useful information. Do not paste a full listing into a public issue, terminal recording or log without checking it first.

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

5. Use 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 is visible in your shell history. If you need more than 20 entries, increase the limit deliberately and consider the amount of account metadata that will appear on screen. A large request can take longer and produces more material to handle safely.

The basic manpage does not promise a machine-readable output format. Avoid writing a parser that depends on column spacing or on the exact wording of descriptions. For automation, use a supported, version-checked interface from the GitHub CLI documentation and test it against the version deployed on the host.

6. Diagnose an empty or failed list

First repeat the read-only checks, in this order:

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

If the unfiltered command works but a focused command returns no rows, that may simply be the account's current visibility mix. If authentication fails, use the CLI's normal login or account-switching procedure rather than placing credentials in the command line. If GitHub reports a network or API error, retry after checking connectivity and the selected host. No recovery command is needed for a list operation because it does not change remote state.