Home / Alt manpages / gh-alias-delete(1)

  • gh-alias-delete(1)
  • User command
  • linux

Remove a GitHub CLI Alias Safely with gh alias delete

Run gh alias delete on the wrong name and GitHub CLI removes it instantly, with no prompt and no undo. This walks you through deleting one alias, checking it is really gone, and knowing exactly when --all turns into a much bigger risk. Allow about five minutes. You need GitHub CLI (gh) installed and a shell account whose aliases you are willing to change. The command only changes your local GitHub CLI configuration; it does not delete a repository, issue or pull request.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command

Start with a read-only check. This needs no sudo and no authenticated GitHub account:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh version
gh version 2.87.3 (2026-02-23)

The installed command used for this guide is GitHub CLI 2.87.3. Your path and version may differ. The local manual describes the same interface as gh alias delete {<alias> | --all} [flags], with one option: --all.

Checkpoint

If command -v gh reports no path, install GitHub CLI through your normal package-management process before continuing. Do not use an unrelated gh binary from another directory without checking which one your shell will run.

2. List aliases before changing anything

Use gh alias list to see the names and expansions currently configured for this installation:

$ gh alias list
co: pr checkout
ll: pr list
ws: workflow list

The output above is an example. Your aliases are personal, and the list can be empty. Pick the exact name on the left of the colon: here, ll is the alias name and pr list is its expansion.

  • Not a shell alias. gh alias delete ll removes the alias used by gh ll. It does not remove a Bash, Zsh or Fish alias also named ll.
  • Not the underlying command. Deleting the alias never changes what pr list itself does.

3. Delete one alias

Deleting a single known alias is an ordinary, local configuration change:

$ gh alias delete ll
$ printf 'exit status: %s\n' "$?"
exit status: 0

A successful exit status means GitHub CLI accepted the deletion. The command normally prints no confirmation, so check the resulting list rather than trusting the silence:

$ gh alias list
co: pr checkout
ws: workflow list

Checkpoint

The deleted name should no longer appear. If it is still there, check that you used the same gh executable and configuration context for both commands. A different installation or an explicitly configured environment can point at different local settings.

4. Recover a deletion when you know the expansion

There is no separate restore option in gh alias delete. If you removed the wrong alias, recreate it with gh alias set, using the expansion you recorded before deletion:

$ gh alias set ll 'pr list'
co: pr checkout
ll: pr list
ws: workflow list
$ gh alias list
co: pr checkout
ll: pr list
ws: workflow list
  • Quote the expansion. That way the shell passes it to GitHub CLI as one argument.
  • Recover the exact wording first. If the old expansion contained shell syntax or several words, pull it from your shell history, dotfiles or another trusted record before recreating it. Do not guess: an alias can run a different command than its short name suggests.

The gh alias set command above is shown only as recovery. Skip it when you are deleting a confirmed, obsolete alias.

5. Treat --all as a destructive shortcut

gh alias delete --all removes every GitHub CLI alias in the current configuration. That is far broader than removing one name, so do not reach for it as a tidy-up shortcut until you have saved anything you might need:

$ gh alias list
co: pr checkout
ll: pr list
ws: workflow list
$ gh alias delete --all
$ gh alias list

The final list is empty once the deletion has completed. There is no confirmation prompt and no built-in undo for this operation. If you need a record before clearing the list, save the output as plain text somewhere you trust:

$ gh alias list > gh-aliases-before-delete.txt
$ gh alias delete --all
$ test ! -s gh-aliases-before-delete.txt && echo 'backup file exists'
backup file exists

Recovery

The saved list is a reference, not a file that gh can import directly. Recreate aliases one by one with gh alias set NAME 'EXPANSION', reviewing each expansion before running it, particularly if the list came from another person or machine.

6. Diagnose the common mistakes

If the command rejects the invocation, check the syntax with the installed help:

$ gh alias delete --help
Delete set aliases

USAGE
  gh alias delete {<alias> | --all} [flags]

FLAGS
  --all   Delete all aliases
  • Pass one thing, not both. Give either one alias name or --all. Do not combine an alias name with --all, and do not add a made-up confirmation flag.
  • Quote unusual names. If the alias name contains shell metacharacters or whitespace, quote it for the shell, then verify the exact name in the list output.
  • Check the whole chain. If a deletion appears not to have worked, compare command -v gh, gh version and gh alias list in the same shell, and check whether a wrapper, container or separate user account is supplying the command.

Warning

Elevated privileges are not a fix here. Running sudo gh alias delete can alter root's configuration instead of yours.

Done means

  • Executable checked. The intended GitHub CLI executable and version were confirmed.
  • Target identified. The alias to remove was picked out from gh alias list.
  • Deletion verified. A named deletion was confirmed by listing aliases again.
  • --all used carefully. It was only run after recording aliases that might need restoring.
  • Nothing else touched. No repository data or shell aliases were changed, and no elevated privileges were needed.