Create, Inspect and Safely Maintain GitHub Gists with gh

You will finish with a practical workflow for managing GitHub gists from a Linux shell: create a small gist, find it again, inspect its files, clone it locally, update it and recognise the irreversible delete operation. The examples target 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 before starting:

$ gh auth status

This 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:

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

The top-level form is gh gist <command> [flags]. The installed command provides clone, create, delete, edit, list, rename and view. None of the examples in this guide needs sudo. These operations use your GitHub account, not local administrator privileges.

Checkpoint: confirm that gh --version succeeds and that gh auth status names the account you intend to use. If the wrong account is active, do not create anything yet.

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 printed by your own run. If the response is a URL, creation succeeded. Without --public, the installed help says the gist is secret, meaning it is not listed publicly, but do not treat that as encryption or as permission to store credentials.

To create a public gist, add --public deliberately:

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

Review the file and its description before doing this. A public gist is intended to be listed and is 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 know whether the gist is public or secret:

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

The filter is a regular expression and can match the description, file names or, with --include-content, file content. Content matching is slower and uses more API rate limit, so add that option only when filename and description matching are not enough.

View the rendered gist, or list its filenames without printing file 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, request one file as raw text:

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

Checkpoint: the URL, description and filename should identify the gist you meant to touch. A gist ID or its full URL is accepted by the subcommands that take a gist argument.

4. Clone a gist for local work

Clone the gist into a new directory. Choose a directory that does not already contain 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 changing the remote gist:

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

The clone is a local Git repository. Editing a file in it does not update the gist until you explicitly use a gist command. If the destination exists, choose another directory 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 selects the remote file and the final filename supplies its replacement content. The command has no preview mode in the installed help, so inspect the local file first and 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. Renaming is a separate operation:

$ 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 command 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 filename change, rename it back using the old and new names in reverse.

6. Delete only after a final check

Deletion is irreversible from the command's point of view. It removes the gist rather than merely hiding it. First inspect the exact URL and files:

$ 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'

Use --yes only in a reviewed, non-interactive operation where the ID has been selected safely:

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

Do not construct a deletion command from untrusted text or a broad list without checking each ID. After deletion, a view command should fail rather than display the gist. A local clone, if you made one, is not a remote recovery service, so preserve any needed copy before deleting.

Common failure signals

• An authentication failure means the CLI needs a valid session. It is not fixed by sudo; check gh auth status and the selected host.
• A missing file during edit or rename usually means the remote filename is not exact. Run gh gist view ID --files and copy the name.
• A clone or create failure can be a network, permission or API-rate problem. Retry only after reading the error; repeating a create command may create a second gist.
• Exit status 0 means the command completed successfully. A normal failure is status 1, cancellation is status 2, and an authentication requirement is status 4, although a particular command can document additional values.