Build Safe, Useful Shortcuts with gh alias set

Type the same three-word gh command often enough and gh alias set turns it into two keystrokes, arguments and all. This guide creates a shortcut, passes it arguments, uses a positional placeholder, and makes a deliberate choice about shell execution. The examples match gh 2.87.3, installed here on 23 February 2026. Allow about ten minutes. You need a shell and the gh package; authentication is only needed when the expanded command talks to GitHub.

An alias changes your local GitHub CLI configuration. It does not create a GitHub repository alias and it is not shared with colleagues automatically. The commands below are ordinary user commands: no elevated privileges are needed.

1. Check the installed command

Confirm which executable and version you are using before copying a guide into a script or team setup:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)

Your path and version may differ. The relevant interface is gh alias set <alias> <expansion> [flags]. The alias name may contain a space, which lets you add a shortcut below an existing gh command.

2. Create a simple command shortcut

Give the alias a short name and quote the expansion so the current shell does not interpret its spaces:

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

The second command expands to the equivalent of gh pr view 123. Arguments that follow an alias are appended to its expansion when the expansion has no positional placeholders. To check the result without making a GitHub request, list the aliases:

$ gh alias list
pv: pr view

If an alias name already exists, gh alias set refuses to replace it. That protects a working shortcut from an accidental typo.

3. Add arguments and grouped command names

Put fixed flags in the expansion when they describe the job the shortcut is for:

$ gh alias set bugs 'issue list --label=bugs'
$ gh bugs
$ gh alias set 'issue mine' 'issue list --mention @me'
$ gh issue mine

These aliases still accept extra arguments: gh bugs --limit 20 appends that limit to the expanded issue-list command. Keep an alias focused on one predictable operation; a long expansion is harder to review and easier to misread.

4. Use a positional argument

Use $1, $2 and similar placeholders when an argument belongs inside the expansion rather than at its end:

$ gh alias set epics 'issue list --author="$1" --label="epic"'
$ gh epics vilmibm
gh issue list --author="vilmibm" --label="epic"

The first argument replaces $1. This suits a repeated filter, but quote the placeholder inside the expansion when it is used as one value; omit placeholders and extra arguments are appended instead. The single quotes in the definition only protect $1 from the shell while you define it. The alias itself keeps the placeholder for GitHub CLI to fill when invoked.

5. Read an expansion from standard input

Use a single hyphen as the expansion when quoting becomes awkward, or when another program is supplying the text:

$ printf '%s' 'issue list --label=bugs' | gh alias set bugs -
$ gh alias list
bugs: issue list --label=bugs

The input is the expansion string, not a command to execute immediately. Treat input from a file or pipeline as configuration you are about to save, and review it before running the alias.

6. Treat shell aliases as executable code

An expansion beginning with !, or an alias defined with --shell, is evaluated by the sh interpreter. That enables pipelines and redirection, but it also makes quoting and untrusted input security concerns:

$ gh alias set --shell say 'printf "%s\\n" "$1"'
$ gh say hello
hello

A practical GitHub example is:

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

• Never put untrusted text into a shell expansion. The pipeline runs through sh, so anything it touches is real code.
• Keep the placeholder quotes. Removing them without understanding word splitting and metacharacters is how a shell alias misfires.
• Prefer a normal alias when it can do the job. A command alias is safer whenever it can express the same task.

Shell aliases can run more than gh commands, including file operations and network clients. Review them with gh alias list as you would review a script. Defining one does not require sudo, and running one as root would only increase the impact of a mistake.

7. Replace or recover an alias

If you intentionally need to change an existing alias, say so explicitly with --clobber:

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

There is no undo flag in gh alias set. Recovery is straightforward: define the old expansion again with --clobber. If you are unsure what it was, stop and check your shell history or a trusted copy before overwriting it. Avoid --clobber in an unattended script unless replacing the alias is the intended result.