Move GitHub CLI Aliases Safely with gh alias import

You will finish with a repeatable way to import GitHub CLI aliases from a YAML file or standard input, check what changed, and avoid replacing an existing alias by accident. The active executable here reports GitHub CLI 2.87.3, released 2026-02-23. Check your own binary because command behaviour can vary between versions.

Allow about ten minutes. You need gh installed and a shell. No GitHub login or elevated privilege is needed: this command changes the GitHub CLI configuration for the current user, not a repository or a system service.

1. Check the installed command

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

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

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

Checkpoint: if your version is different, run its help and keep the syntax that it reports. Do not assume that an option from a newer manual is available in this installation.

2. Inspect the aliases already on this machine

Import is a state-changing operation, so capture the current list first. The ordinary command needs no sudo:

$ gh alias list
co: pr checkout

Your output will differ. The list is useful as a before-and-after record, particularly when the input contains a name you already use. Aliases are stored in gh's user configuration directory. To see which directory 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 does 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 and 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

Use a normal file such as aliases.yml when you are transferring a saved set:

$ 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, list, or value that is not a string is not the documented shape. Treat imported YAML as executable configuration: review expansions for unexpected commands, pipelines, redirects, substitutions, and credentials before running them.

Checkpoint: confirm the spelling of every alias and decide whether each expansion is safe for your account. YAML quoting is part of the alias value, so preserve quotes around shell arguments where they matter.

4. Import from a file without replacing aliases

Run the import as your ordinary user:

$ gh alias import aliases.yml

With valid YAML and no conflict, gh normally completes without a success message. Verify the resulting map explicitly:

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

Output order and the presence of other aliases depend on your existing configuration. The important check is that the imported names and expansions appear as intended.

If an alias already exists, leave out --clobber on the first attempt. This protects the existing expansion. A conflict is a review point, not a reason to add the option blindly.

5. Use standard input for a one-off transfer

A hyphen tells gh to read YAML from standard input. This avoids 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, which keeps the intended alias text intact.

Standard input is also useful when 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 deliberately

Only use --clobber 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 a named alias; it permits replacement for any same-named entries in the imported map. Do not combine it with an unreviewed file.

This is a configuration change, not a destructive system operation, but it can change the command you run under a short alias. If the result is wrong, restore the old value by importing a corrected YAML entry, or delete the alias and recreate it:

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

Deleting an alias is irreversible unless you recorded its old expansion. The delete command is ordinary user configuration work and does not need elevated privileges.

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. If an import fails, verify the alias list before making another change:

$ gh alias list
$ gh alias import --help

For a missing file, check the path with test -r aliases.yml. For a permission error, fix ownership or permissions on the file you intend to read; running the import with sudo would target a different user's configuration and is usually the wrong recovery.