Create, Inspect and Safely Maintain GitHub Gists with gh

Every gist you have pasted into a chat and then lost is a search problem that gh gist solves from the terminal. This guide creates one, finds it again, inspects it, clones it, edits it and deletes it properly, using GitHub CLI gh 2.87.3, installed here on 23 September 2026.

Allow about fifteen minutes. You need the gh package, a GitHub account that can use gists, and an authenticated CLI session.

• Check authentication first. Run gh auth status before anything else.

$ gh auth status

That is an ordinary user command. If it reports that authentication is required, stop and run gh auth login through your normal account-approval process. Do not put an access token into a gist, shell history or an article example.

1. Check the installed command

Read the local command contract before using a flag you have not tried:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh gist --help

• The top-level form is gh gist <command> [flags].
• The installed subcommands are clone, create, delete, edit, list, rename and view.
• None of them need sudo. These are your GitHub account's operations, not the machine's.

2. Create a private-by-default gist

Create a local example file with content that is safe to publish to GitHub. This writes only in your current directory:

$ printf '%s\n' '#!/bin/sh' 'printf "gist smoke test\\n"' > gist-smoke.sh
$ gh gist create gist-smoke.sh --desc 'Small shell smoke test'
https://gist.github.com/OWNER/GIST_ID

Replace OWNER/GIST_ID in later commands with the URL your own run prints. A URL back means creation worked. Without --public, the installed help calls the gist secret: unlisted, not encrypted, and still not a place to store credentials.

To create a public gist, add --public on purpose:

$ gh gist create --public README.txt --desc 'Public example notes'

Review the file and its description first. A public gist is meant to be found, which makes it a poor place for logs containing hostnames, email addresses, tokens or private source.

3. Find and inspect the gist

List recent gists owned by the authenticated account:

$ gh gist list --limit 10

The default limit is 10. Narrow the result when you already know whether the gist is public or secret:

$ gh gist list --secret --filter 'smoke test'

The filter is a regular expression that can match the description, the file names, or, with --include-content, the file content. Content matching is slower and burns more API rate limit, so reach for it only when filename and description matching come up empty.

View the rendered gist, or list its filenames without printing the contents:

$ gh gist view 'https://gist.github.com/OWNER/GIST_ID'
$ gh gist view 'https://gist.github.com/OWNER/GIST_ID' --files

For a script or configuration fragment, pull one file as raw text:

$ gh gist view 'https://gist.github.com/OWNER/GIST_ID' --filename gist-smoke.sh --raw

4. Clone a gist for local work

Clone the gist into a new directory. Pick one that does not already hold work you need:

$ gh gist clone 'https://gist.github.com/OWNER/GIST_ID' gist-smoke-local
Cloning into 'gist-smoke-local'...

Verify the checkout without touching the remote gist:

$ git -C gist-smoke-local status --short
$ git -C gist-smoke-local remote -v

The clone is an ordinary local Git repository. Editing a file in it does nothing to the gist until you run a gist command. If the destination directory already exists, pick another name rather than deleting it to make the clone fit.

5. Edit content or metadata

Replace one existing file from a reviewed local file:

$ printf '%s\n' '#!/bin/sh' 'printf "updated gist smoke test\\n"' > gist-smoke.sh
$ gh gist edit 'https://gist.github.com/OWNER/GIST_ID' --filename gist-smoke.sh gist-smoke.sh

The first filename picks the remote file; the last one supplies its replacement content. There is no preview mode in the installed help, so check the local file first, then verify the remote result:

$ gh gist view 'https://gist.github.com/OWNER/GIST_ID' --filename gist-smoke.sh --raw
#!/bin/sh
printf "updated gist smoke test\n"

Change only the description with --desc:

$ gh gist edit 'https://gist.github.com/OWNER/GIST_ID' --desc 'Reviewed shell smoke test'

• Add a file with --add NEW_FILE.
• Remove a remote file with --remove OLD_FILE. Treat that as destructive and confirm with gh gist view --files afterwards.
• Rename separately. Renaming is its own operation, not a flag on edit.

$ gh gist rename 'https://gist.github.com/OWNER/GIST_ID' gist-smoke.sh smoke-test.sh
$ gh gist view 'https://gist.github.com/OWNER/GIST_ID' --files

There is no general undo in the gh gist interface. To recover an accidental content change, keep a known-good local copy and submit it again with gh gist edit. For a rename gone wrong, run it again with the old and new names swapped.

6. Delete only after a final check

Deletion removes the gist outright; it does not just hide it, and it cannot be undone from the command's side. Inspect the exact URL and files first:

$ gh gist view 'https://gist.github.com/OWNER/GIST_ID' --files
$ gh gist view 'https://gist.github.com/OWNER/GIST_ID'

The interactive form asks for confirmation:

$ gh gist delete 'https://gist.github.com/OWNER/GIST_ID'

$ gh gist delete 'https://gist.github.com/OWNER/GIST_ID' --yes

After deletion, a view command should fail rather than show the gist. A local clone, if you made one, is not a remote backup, so keep any copy you need before deleting.

Common failure signals

• Authentication failure. The CLI needs a valid session; sudo will not fix it. Check gh auth status and the selected host.
• Missing file during edit or rename. The remote filename is probably not exact. Run gh gist view ID --files and copy the name shown.
• Clone or create failure. Usually a network, permission or API-rate problem. Read the error before retrying: repeating a create command can leave you with a second gist.
• Exit codes. 0 is success, 1 is a normal failure, 2 is cancellation, and 4 means authentication is required, though a particular command can add more values.