Edit a GitHub Gist Safely with gh gist edit

A typo in a gist you shared with the team is live the moment someone opens the link. gh gist edit fixes it from the terminal: change the description, replace a file, add one or remove one. Allow about ten minutes if you already know the gist ID and have authenticated gh.

The examples use GitHub CLI 2.87.3, installed on this machine.

• This changes data on GitHub. Make sure you have the right account, gist and local source file.
• No 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 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.

2. Check authentication and identify the target

Check the account 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 extra lines vary. If the check says 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 one in a gist.

Use the complete gist URL when there is any doubt about the ID. A URL is easier to review in 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 that gh gist view prints. Replace the placeholder URL with the gist you intend to change. This guide does not assume the 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 you supply. Keep the new text quoted so spaces stay in 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

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

4. Replace one file from a reviewed local file

Name the file to edit, then give a local file path as a second positional argument. The command reads that 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.

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

5. Add a new file without touching the others

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 in the gist before adding it. A duplicate-name result is a reason to stop and inspect the gist, not a prompt to overwrite another file by accident.

6. Remove a file after checking its name

Removal is destructive to the gist's current file set. gh gist edit has no undo flag, 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

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

The restored file carries the backup's name. If you need the original name, rename the local copy to commands.sh before adding it, or fix the name in the GitHub web interface after verifying the content.

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

These modes suit a terminal but are poor fits for unattended scripts, because they depend on prompts and editor configuration:

• No arguments. gh gist edit selects a gist interactively.
• Gist ID, no file name. It opens a file in the default editor.

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

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