Rename a Gist File Safely with gh gist rename

A gist file called untitled.txt is a small embarrassment waiting to be linked. gh gist rename renames one file inside an existing GitHub gist, and you then check the new name is there. It takes about five minutes if you know the gist and both filenames.

The command changes the remote gist, so keep the old name to hand until you have checked the result and know how to reverse it.

• You need: GitHub CLI, an authenticated account that can edit the gist, and its short ID or full URL.
• Placeholders are harmless. Replace every value in angle brackets before running a command.

1. Check the installed command

Check which executable your shell will run and read its help:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh gist rename --help
Rename a file in the given gist ID / URL.

The local executable reports GitHub CLI 2.87.3. The Ubuntu package database on this machine reports a different package version, 2.45.0-1ubuntu0.3+esm3, so identify the binary in your own PATH rather than assuming the package version describes it. The installed manpage is dated March 2026 and documents the same positional interface.

2. Confirm the account and target

Before changing anything, make sure the target is the gist you intend to edit. You can use the short gist ID or its URL. To inspect its files first, view it:

$ gh gist view <gist-id-or-url>

• Check filenames character by character. They are case-sensitive.
• Quote names with spaces. They must reach the shell as one argument.
• Never guess. Do not copy a filename from an unrelated gist tab or use a guessed ID.

The rename needs your GitHub authentication and permission to edit that gist. It does not need root.

3. Rename a straightforward filename

Pass the gist identifier, the current filename and the replacement filename, in that order:

$ gh gist rename <gist-id-or-url> notes.txt notes-2026.txt

For example, a real command might look like this:

$ gh gist rename 0123456789abcdef0123456789abcdef notes.txt notes-2026.txt

This renames a file in the specified gist. It does not rename a local file and it does not change the file contents. A successful run may print nothing useful, so use the exit status and then inspect the gist:

$ status=$?
$ printf 'gh gist rename exit status: %s\n' "$status"
gh gist rename exit status: 0
$ gh gist view 0123456789abcdef0123456789abcdef

4. Quote names that contain shell syntax

The shell parses arguments before gh sees them. Quote names containing spaces, brackets, dollar signs, wildcard characters or other punctuation:

$ gh gist rename <gist-id-or-url> 'draft notes.txt' 'published notes.txt'
$ gh gist view <gist-id-or-url>

• Prefer single quotes. When a filename contains a dollar sign or backticks, the shell leaves single-quoted contents unchanged.
• Watch for single quotes in the name. Use double quotes carefully, or build the argument with shell quoting you have tested separately.
• Avoid bare *, ? and spaces. A wildcard can expand to local filenames, giving the wrong number of arguments or the wrong target name.

5. Recover from a wrong rename

Renaming changes remote state. If you chose the wrong replacement name and the request succeeded, the normal undo is another rename from the new name back to the original:

$ gh gist rename <gist-id-or-url> notes-2026.txt notes.txt
$ gh gist view <gist-id-or-url>

If the command fails, read the error, check authentication and permission, and verify the old filename. A successful HTTP request followed by an interrupted terminal session can leave you unsure of the result, which is why the follow-up view matters.