Move GitHub CLI Aliases with gh alias import

You have a set of GitHub CLI aliases on one machine and you want them on another, without trampling the ones already there. This guide covers gh alias import from a YAML file or standard input, checking what changed, and knowing when --clobber is safe. It takes about ten minutes.

• What you need: gh installed and a shell. The active executable here reports GitHub CLI 2.87.3, released 2026-02-23, so check your own binary because behaviour can vary between versions.
• Privileges: none. No GitHub login and no sudo.
• What it touches: the GitHub CLI configuration for the current user. Not a repository, not a system service.

1. Check the installed command

Read the local help before preparing a file. This is read-only:

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

The command takes one input argument: a YAML filename, or - for standard input. Its only option is --clobber, which overwrites an existing alias with the same name.

2. Record the aliases you already have

Import changes state, so capture the current list first. The ordinary command needs no sudo:

$ gh alias list
co: pr checkout

Your output will differ. Keep it as a before-and-after record, especially if the incoming file reuses a name you already have.

Aliases live in gh's user configuration directory. To find which one gh uses, inspect the GH_CONFIG_DIR setting and the GitHub CLI environment help. Do not edit a guessed file while troubleshooting.

For a dry review of a proposed transfer, compare the YAML names with this list. Import will not merge two different expansions under one name unless you explicitly allow replacement.

3. Prepare a small YAML map

Each top-level YAML key is an alias name. Its value is the expansion gh will run. Keep the first transfer small enough to review:

bugs: issue list --label=bug
igrep: '!gh issue list --label="$1" | grep "$2"'
features: |-
  issue list
  --label=enhancement

For a saved set, use a normal file such as aliases.yml:

$ sed -n '1,80p' aliases.yml
bugs: issue list --label=bug
igrep: '!gh issue list --label="$1" | grep "$2"'

The top level must be a map of strings. A scalar, a list or a non-string value is not the documented shape.

4. Import from a file without replacing anything

Run the import as your ordinary user:

$ gh alias import aliases.yml

With valid YAML and no conflict, gh normally finishes without a success message. Check the result yourself:

$ gh alias list
bugs: issue list --label=bug
co: pr checkout
igrep: '!gh issue list --label="$1" | grep "$2"'

Output order and any other aliases depend on your existing configuration. What matters is that the imported names and expansions appear as intended.

5. Import from standard input

A hyphen tells gh to read YAML from standard input, which saves creating a temporary file:

$ printf '%s\n' \
  'review: pr list --reviewer=YOUR_GITHUB_LOGIN' \
  'mine: issue list --assignee=@me' | gh alias import -
$ gh alias list
mine: issue list --assignee=@me
review: pr list --reviewer=YOUR_GITHUB_LOGIN

Replace YOUR_GITHUB_LOGIN before running the example. The shell expands nothing inside those single-quoted YAML lines, so the alias text arrives intact.

Standard input also suits moving the output of gh alias list from another machine. Treat that output as configuration to review, not as a command to execute directly.

6. Replace a conflict on purpose

Use --clobber only after comparing the old and new values:

$ gh alias list | grep '^bugs:'
bugs: issue list --label=bug
$ gh alias import --clobber aliases.yml
$ gh alias list | grep '^bugs:'
bugs: issue list --label=regression

The exact output depends on your file. --clobber is not limited to one named alias: it permits replacement for every same-named entry in the imported map.

This is a configuration change, not a destructive system operation, but it can change what a short alias runs. If the result is wrong, import a corrected YAML entry, or delete the alias and recreate it:

$ gh alias delete bugs
$ gh alias list | grep '^bugs:' || echo 'bugs alias removed'

7. Diagnose a failed import

A YAML parsing error usually means the document is not a top-level map, or has quoting or indentation problems. Check the file with line numbers, correct it, then retry:

$ nl -ba aliases.yml | sed -n '1,80p'
$ gh alias import aliases.yml
yaml: unmarshal errors:
  line 1: cannot unmarshal ... into map[string]string

The wording and line number vary. Do not add --clobber to fix malformed YAML. After any failed import, look at the alias list before you change anything else:

$ gh alias list
$ gh alias import --help

• Missing file. Check the path with test -r aliases.yml.
• Permission error. Fix ownership or permissions on the file you meant to read.
• Do not reach for sudo. It would target a different user's configuration, so it is usually the wrong recovery.