Aliases — Understanding GitHub CLI

Aliases let you create shortcuts for frequently used gh commands. They save typing and let you build custom workflows.

Creating Aliases

# Simple alias
gh alias set co 'pr checkout'
gh alias set pvw 'pr view --web'
gh alias set il 'issue list'
 
# Now you can use them
gh co 123              # Expands to: gh pr checkout 123
gh pvw 42              # Expands to: gh pr view 42 --web
gh il --label bug      # Expands to: gh issue list --label bug

Arguments are appended to the expanded command.

Listing Aliases

gh alias list

Output:

co:   pr checkout
il:   issue list
pvw:  pr view --web

Deleting Aliases

gh alias delete pvw

Importing Aliases

Import aliases from a YAML file:

gh alias import aliases.yml

File format (aliases.yml):

co: pr checkout
pvw: pr view --web
il: issue list
rv: repo view --web

This is useful for sharing aliases across machines or with a team.

Shell Aliases (`--shell`)

For aliases that need shell features (pipes, command substitution, conditionals), use --shell:

# Use command substitution
gh alias set --shell repo-name 'gh repo view --json nameWithOwner --jq .nameWithOwner'
 
# Use pipes
gh alias set --shell my-issues 'gh issue list --assignee @me --json number,title --jq ".[] | \"#\(.number) \(.title)\""'
 
# Use positional parameters
gh alias set --shell create-repo 'gh repo create "$1" --public --clone'
 
# Complex example: create a repo under an org using the current directory name
gh alias set --shell rcd 'gh repo create my-org/$(basename "$PWD") --public -y'

Positional Parameters in Shell Aliases

Shell aliases support $1, $2, etc.:

gh alias set --shell pr-for 'gh pr list --author "$1" --state open'
 
# Usage
gh pr-for octocat

Where Aliases Are Stored

Aliases live in ~/.config/gh/config.yml:

aliases:
  co: pr checkout
  pvw: pr view --web
  il: issue list
  repo-name: '!gh repo view --json nameWithOwner --jq .nameWithOwner'

Shell aliases are prefixed with ! in the config file.

You can edit this file directly instead of using gh alias set.

Useful Alias Ideas

# Quick PR workflow
gh alias set prc 'pr create'
gh alias set prm 'pr merge --squash --delete-branch'
gh alias set prs 'pr status'
gh alias set prd 'pr diff'
 
# Issue shortcuts
gh alias set ic 'issue create'
gh alias set iv 'issue view --web'
gh alias set is 'issue status'
 
# Repository shortcuts
gh alias set rv 'repo view --web'
gh alias set rc 'repo clone'
 
# Actions shortcuts
gh alias set rl 'run list'
gh alias set rw 'run watch'
 
# Open current repo in browser
gh alias set browse 'repo view --web'
 
# List my open PRs across all repos
gh alias set --shell my-prs 'gh search prs --author @me --state open --json repository,title,number --jq ".[] | \"\(.repository.nameWithOwner)#\(.number) \(.title)\""'

Combining with Shell Aliases

You can also create regular shell aliases that wrap gh:

# In ~/.bashrc or ~/.zshrc
alias ghdi='git init && git add . && git commit -m "Initial commit" && gh repo create --source=. --public --push && gh repo view --web'

Exercises

Create an alias: gh alias set co 'pr checkout'
List your aliases: gh alias list
Use the alias: gh co 1 (on a repo with a PR)
Create a shell alias: gh alias set --shell whoami 'gh api user --jq .login'
Try it: gh whoami
Clean up: gh alias delete co && gh alias delete whoami