Edit a GitHub Gist Safely with gh gist edit

You will finish with a repeatable way to change a gist's description, edit an existing file, add a file or remove one. The examples use GitHub CLI 2.87.3, installed on this machine. Allow about ten minutes if you already know the gist ID and have authenticated gh.

This command changes data on GitHub. Before you start, make sure you have the right account, gist and local source file. No example needs elevated privileges: do not use sudo for GitHub CLI authentication or gist editing.

1. Check the installed command

Confirm which executable is being used and record the version. These are ordinary read-only checks:

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

Read the command's local help before copying an example. The installed interface is gh gist edit {<id> | <url>} [<filename>] [flags]. It accepts a gist ID or URL, and the optional file name selects a file to edit.

Checkpoint: if gh --version reports a different release, run gh gist edit --help and compare the available flags before using this guide in a script.

2. Check authentication and identify the target

Use the account check before making a remote change:

$ gh auth status
github.com
  Logged in to github.com account YOUR_ACCOUNT
  Active account: true

The account name and additional lines vary. If the check says that you are not logged in, stop and authenticate through your normal GitHub CLI process. Do not paste a token into a command line or put a token in a gist.

Use the complete gist URL when there is any doubt about the ID. A URL is easier to review in a shell history and less likely to point at a similarly named gist:

GIST='https://gist.github.com/YOUR_ACCOUNT/0123456789abcdef0123456789abcdef'
gh gist view "$GIST"

Review the file names and description printed by gh gist view. Replace the placeholder URL with the gist you intend to change. This guide does not assume that a gist is public or that you own every gist whose URL you can read.

3. Change only the description

The --desc flag replaces the gist description with the string supplied. Keep the new text quoted so spaces remain part of one argument:

$ gh gist edit "$GIST" --desc 'Short shell notes for the backup host'
$ printf 'exit status: %s\n' "$?"
exit status: 0

A status of zero means the CLI completed the request. It is not a before-and-after comparison, so view the gist again when the description matters:

$ gh gist view "$GIST"
Short shell notes for the backup host

The description flag does not add to the existing description. Save the old text first if you may need to restore it. Recovery is simply another edit with the previous description:

$ gh gist edit "$GIST" --desc 'YOUR_PREVIOUS_DESCRIPTION'

4. Replace one file from a reviewed local file

Editing a named file with a second positional file path reads the local file and uses it as the replacement content:

$ FILE='notes.txt'
$ cp -- "$FILE" "$FILE.backup"
$ gh gist edit "$GIST" --filename "$FILE" "$FILE"
$ gh gist view "$GIST" --filename "$FILE"
updated line one
updated line two

Review $FILE before running the edit. The command changes the remote gist, not just a working copy. The backup above protects your local source, but it does not automatically undo the remote change. To recover, restore the reviewed backup over the local file and submit it again:

$ cp -- "$FILE.backup" "$FILE"
$ gh gist edit "$GIST" --filename "$FILE" "$FILE"
$ gh gist view "$GIST" --filename "$FILE"

Do not use shell input redirection as a substitute for the documented positional file argument. The local file path is the explicit source for this operation.

5. Add a new file without changing an existing one

Use --add with the name of a new file. The command reads that local file and adds it to the gist:

$ NEW_FILE='commands.sh'
$ test -r "$NEW_FILE" && printf '%s\n' 'local file is readable'
local file is readable
$ gh gist edit "$GIST" --add "$NEW_FILE"
$ gh gist view "$GIST"
commands.sh

Check that the file name is not already present before adding it. Treat a duplicate-name result as a reason to stop and inspect the gist, not as a prompt to overwrite another file accidentally. If the addition was wrong, remove that file using the next step, then verify the file list.

6. Remove a file only after checking its name

Removal is destructive to the gist's current file set. There is no separate undo flag in gh gist edit, so save the content locally before issuing --remove:

$ gh gist view "$GIST" --filename 'commands.sh' > commands.sh.before-remove
$ test -s commands.sh.before-remove && printf '%s\n' 'backup captured'
backup captured
$ gh gist edit "$GIST" --remove 'commands.sh'
$ gh gist view "$GIST"
commands.sh

The final output should no longer list commands.sh. If it still appears, inspect the command result and the exact file name. To restore the removed file, add the saved copy:

$ gh gist edit "$GIST" --add commands.sh.before-remove
$ gh gist view "$GIST"
commands.sh.before-remove

That restoration uses the backup's file name. If the original name is required, rename the local copy to commands.sh before adding it, or use the GitHub web interface to correct the name after verifying the content.

7. Use interactive editing only when you can review the target

With no target arguments, gh gist edit selects a gist interactively. With a gist ID but no file name, it opens a file in the default editor. These modes are useful at a terminal, but they are poor fits for unattended scripts because they depend on prompts and editor configuration:

$ gh gist edit
# Select a gist to edit interactively
$ gh gist edit 0123456789abcdef0123456789abcdef
# Edit a gist file in the default editor

For repeatable work, pass the URL or ID, the file name and the local source explicitly. Keep an editor session open long enough to review the whole file, and cancel without saving if the selected gist or file is wrong. An editor's save action is still a remote content change when the CLI submits it.

8. Diagnose failures without guessing

A non-zero status means the operation did not complete successfully. Recheck authentication, the exact gist URL, file names and local read permissions before retrying:

$ test -r "$FILE" && printf '%s\n' 'source is readable'
$ gh auth status
$ gh gist view "$GIST"
$ gh gist edit --help

Do not repeat a removal or replacement blindly after a network timeout. First view the gist and compare it with the saved local copy. The request may have reached GitHub even if the client did not display a successful response. Retry only after you know whether the remote state changed.

Keep secrets out of command output and shell history. File contents can be exposed by gh gist view, terminal scrollback and logs, so do not use a gist as a place to store passwords, access tokens or private keys.