Create Safe, Reusable Shortcuts with gh alias

gh alias turns a long GitHub CLI command you type ten times a day into a short one, with placeholders for the bits that change each time. You will finish with a small set of aliases, a way to pass arguments to them, and a reversible export you can reuse on another machine. Allow about fifteen minutes.

You need GitHub CLI (the installed executable here is gh 2.87.3 at /home/linuxbrew/.linuxbrew/bin/gh) and a shell. No command in this guide needs elevated privileges. The examples below do not authenticate you, change a repository, or contact GitHub unless you invoke an alias that does so.

1. Check the Command Before Changing Configuration

Read the command's own help and confirm which executable will receive your aliases:

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

Checkpoint: If command -v gh names a different installation, keep that version in mind when comparing output. The system package database also has a separate gh package record on this machine, but the executable used for these checks is the Homebrew installation shown above.

2. Add a Read-Only Shortcut

Use gh alias set with an alias name and the command it should expand to. This example creates pv for pull request viewing:

$ gh alias set pv 'pr view'
$ gh pv 123

The second command expands to gh pr view 123. Extra arguments get appended when the expansion has no positional placeholders. The alias lives in gh's own configuration, so this is a persistent change to your user account, though it does not touch GitHub data.

List the configured aliases straight away:

$ gh alias list
co: pr checkout
pv: pr view

Checkpoint: Your output may include aliases that already existed, such as co. Look for the new name and verify its expansion here before using it in a script.

3. Decide How Arguments Should Work

For a fixed filter, put the complete expansion in one quoted shell argument:

$ gh alias set bugs 'issue list --label=bugs'
$ gh bugs

For a reusable value, include positional placeholders such as $1. Quote the expansion so your current shell does not expand the variable while the alias is being created:

$ gh alias set epicsBy 'issue list --author="$1" --label="epic"'
$ gh epicsBy EXAMPLE_USER

EXAMPLE_USER replaces $1 when the alias runs; use a real GitHub login only once you are ready to query GitHub. Extra arguments are appended when the expansion has no placeholders, and inserted into those positions when it does. That difference is easy to miss when an alias appears to work for one invocation but not another.

4. Treat Shell Aliases as Executable Code

An expansion beginning with !, or one created with --shell, is passed to sh. That enables pipelines and redirection, but it also makes quoting and untrusted input a security boundary:

$ gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
$ gh igrep EXAMPLE_LABEL EXAMPLE_TEXT

Warning: Only use shell aliases you have read and understood. Do not copy an alias containing an untrusted command, command substitution or redirection into your configuration. Prefer an ordinary alias for a single GitHub CLI command, and test shell aliases with harmless, read-only commands before adapting them to create, edit or delete operations.

5. Export Aliases Before Sharing or Replacing Them

The output from gh alias list is meant to be usable as YAML input. Save it somewhere private if it contains internal repository names or sensitive command arguments:

$ gh alias list > aliases.yml
$ sed -n '1,120p' aliases.yml
$ gh alias import aliases.yml

Importing without --clobber is the safer default when names might overlap. To import from standard input, use a YAML map and a single hyphen:

$ printf '%s\n' 'review: pr view --comments' | gh alias import -

Warning: Before importing a file from someone else, inspect every value. A YAML value beginning with ! can define shell behaviour, and a multiline value can hide more than one command line.

6. Replace or Undo an Alias Deliberately

Setting an existing name normally fails rather than silently replacing it. Once you have compared the old and new expansions, use --clobber:

$ gh alias set --clobber pv 'pr view --comments'
$ gh alias list
pv: pr view --comments

To recover, re-run the original gh alias set command, or import a known-good export. To remove one alias, name it explicitly:

$ gh alias delete bugs
$ gh alias list

Warning: That deletion is immediate. The command also offers gh alias delete --all, which removes every alias: treat it as destructive, take an export first, and do not reach for it as a troubleshooting shortcut.

Done means