Build Safe, Useful Shortcuts with gh alias set

You will create a GitHub CLI alias, pass it arguments, use a positional placeholder, and make 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.

Checkpoint: if gh --version fails, install or enable GitHub CLI through your normal package-management process before defining aliases.

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 inspect 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. This 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 additional arguments. For example, gh bugs --limit 20 appends that limit to the expanded issue-list command. Keep the alias focused on one predictable operation; a long expansion is harder to review and easier to misread.

Checkpoint: run gh alias list after each definition. It prints the stored expansion, so you can catch missing quotes or a flag attached to the wrong command before using the shortcut in a script.

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"

Here the first argument replaces $1. This is useful for a repeated filter, but quote the placeholder inside the expansion when it is being used as one value. If you omit placeholders, extra arguments are appended instead.

Do not confuse the single quotes in the definition with characters stored in the alias. They protect $1 from the shell while you define it. The alias itself retains 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. This 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

The alias runs a pipeline through sh. Do not put untrusted text into a shell expansion, and do not remove the quotes around placeholders without understanding shell word splitting and metacharacters. A normal command alias is safer when it can express the 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 inspect your shell history or a trusted copy before overwriting it. Avoid using --clobber in an unattended script unless replacing the alias is the intended result.