Audit GitHub CLI Shortcuts with gh alias list

A colleague pastes a command you have never seen, and gh alias list is the fastest way to find out what it actually runs. This guide gets you a reliable view of every configured alias, what each one expands to, and a short path for chasing down one that is missing or behaves differently between two machines. Allow about five minutes. You need an ordinary shell and an installed gh command. Authentication is not required, and none of the commands here need sudo: the command only reports local configuration and never touches GitHub or a repository.

1. Check the installed command

Confirm which executable your shell will run and record its version:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3

The exact path and version will vary. Version matters when comparing output from another machine, because GitHub CLI commands can gain or alter behaviour between releases. If command -v gh prints nothing, install GitHub CLI through your normal distribution or vendor process before continuing rather than guessing a path.

Checkpoint: You have confirmed that gh is installed and know which version you are inspecting.

2. List every configured alias

Run the command without a repository, hostname or authentication token:

$ gh alias list
co: pr checkout

Each line has the alias name on the left, a colon, then the GitHub CLI command it expands to. Here, co is a local shortcut for gh pr checkout. Your output may hold several lines, or none if nothing is configured; aliases are local to the current user's GitHub CLI configuration.

There are no command-specific flags in GitHub CLI 2.87.3, just the documented synopsis gh alias list [flags] and the inherited --help. The gh alias ls spelling also works on this installation:

$ gh alias list --help
This command prints out all of the aliases gh is configured to use.

USAGE
  gh alias list [flags]

ALIASES
  gh alias ls

Tip: Copy the alias list into your notes when comparing two machines. Treat an empty result as a configuration result, not as proof that GitHub CLI is broken.

3. Read an alias as a command expansion

Use the right-hand side as the command to compare with the shortcut. For the example above:

$ gh co --help
$ gh pr checkout --help

Both should describe the same underlying subcommand. An alias is not a shell alias: it is interpreted by gh after the executable has started, so it will not expand in a command that does not begin with gh, such as co by itself, and it does not touch Git's own aliases.

Arguments normally follow the expansion. If an alias expands to pr checkout, an argument supplied after gh co is handled by gh pr checkout. Read the complete line before using it in a script, particularly when the expansion contains shell syntax or a command that can change remote state.

4. Compare aliases without changing either machine

Run the same read-only command on each host and save the output in a temporary file or your terminal history:

$ gh alias list | sort
co: pr checkout
issue-view: issue view

Sorting keeps the comparison stable when configuration order differs between hosts. Do not assume a name is safe because it looks familiar: read the complete expansion. A short name could invoke a command that creates, edits, deletes or merges GitHub data.

5. Diagnose a missing or surprising alias

Ask for the alias command help before changing anything:

$ gh alias --help
Aliases can be used to make shortcuts for gh commands or to compose multiple commands.

AVAILABLE COMMANDS
  delete:        Delete set aliases
  import:        Import aliases from a YAML file
  list:          List your aliases
  set:           Create a shortcut for a gh command

If an expected alias is absent, it has not been loaded into the configuration this invocation is using, or it was removed. Check the account, executable path and environment before recreating it. If an alias is present but its expansion looks wrong, stop and inspect the full right-hand side rather than running an unfamiliar expansion just to see what it does.

The list command itself has no edit or delete operation; those are separate subcommands. If you later use gh alias set or gh alias delete, treat that as a configuration change: record the previous line first so you can restore it. There is no need for elevated privileges with a per-user alias.

6. Keep scripts reproducible

Aliases are convenient at an interactive prompt but can hide the real command in a script, runbook or incident record. For automation, prefer the full command such as gh pr checkout and keep the alias as a personal convenience. If a script deliberately depends on an alias, make the prerequisite explicit and verify it early:

$ gh alias list | grep -F '^co: '
co: pr checkout

A missing match produces no output and a non-zero status from grep, which is useful in a guarded check but should not be confused with an error from gh alias list itself. For portability across machines, test the real command rather than requiring every operator to share the same aliases.

Done means