Enable gh Shell Completion Without Guessing Where It Belongs

Tab completion for gh is not switched on by default, and typing the full subcommand every time gets old fast. This sets it up for whichever shell you actually use, reloads that shell, and confirms that gh offers subcommands and options as you type. The examples are for the installed GitHub CLI 2.87.3 and take about five minutes. Completion only touches shell startup files or adds one generated script; it does not change a repository or a GitHub account.

Before you start

1. Check that gh is installed and identify your shell.

gh --version
printf '%s\n' "$SHELL"

On the machine used for this guide, the first command reports gh version 2.87.3. The completion command supports exactly four values: bash, zsh, fish and powershell. This guide covers the three Unix shells. If your package manager already installed a completion integration, you may need no extra configuration.

Tip: Use the matching section below for your shell, and do not paste all three examples into the same startup file. A useful second check is ps -p $$ -o comm=, which reports the shell running the current interactive session.

1. Configure Bash

The installed manual recommends bash-completion and an evaluation line in ~/.bash_profile. Install the package using your distribution's normal package manager if Bash completion is not already available. Installing packages may require elevated privileges; the configuration line itself does not.

printf '%s\n' 'eval "$(gh completion -s bash)"' >> ~/.bash_profile

The command appends one line to your profile. Inspect it before opening a new shell:

tail -n 3 ~/.bash_profile

Open a new login shell, or source the file if that is how your shell is normally started:

source ~/.bash_profile
gh <TAB>

You should see GitHub CLI subcommands such as auth, issue and repo. If your terminal starts Bash through a configuration that does not read .bash_profile, put the same line in the startup file that your existing Bash setup loads. To undo this guide's change, remove only the appended eval line, then start a fresh shell.

2. Configure Zsh

Zsh loads completion functions from directories in $fpath. A user-local directory avoids writing under /usr/local and normally needs no administrator access.

mkdir -p ~/.zsh/completions
gh completion -s zsh > ~/.zsh/completions/_gh
printf '%s\n' 'fpath=(~/.zsh/completions $fpath)' 'autoload -U compinit' 'compinit -i' >> ~/.zshrc

Start a new Zsh session, or reload the configuration:

source ~/.zshrc
gh <TAB>

The generated file should begin with #compdef gh. Check it without printing the whole script:

head -n 1 ~/.zsh/completions/_gh

Zsh 5.7 or later is recommended by the manual. If completion remains absent, check that the directory appears in the path:

print -l $fpath | grep -Fx "$HOME/.zsh/completions"

To undo the setup, remove the three lines added to ~/.zshrc and the generated ~/.zsh/completions/_gh file. That file is generated output; do not remove other completion files in the directory.

3. Configure Fish

Fish looks for completion functions in ~/.config/fish/completions. Create that directory and write the generated script there:

mkdir -p ~/.config/fish/completions
gh completion -s fish > ~/.config/fish/completions/gh.fish

Start a new Fish session. You can also run the command below to confirm that the file contains a Fish function:

head -n 3 ~/.config/fish/completions/gh.fish

Type gh and press Tab. Fish should display available subcommands. The generated file is read when Fish starts, so restarting the shell is the least surprising test. To undo this setup, delete only ~/.config/fish/completions/gh.fish and start Fish again.

Common failure points

• Wrong shell: a Bash script will not be loaded by Zsh or Fish. Check $SHELL and the current process before changing files.
• Stale session: completion is loaded by shell startup or by sourcing the relevant file. Restart the shell after generating a script.
• Broken redirection: > replaces the generated completion file. That is intentional here, but do not point it at a hand-written configuration file.
• Permission errors: the user-local examples should not need sudo. A system-wide Zsh path such as /usr/local/share/zsh/site-functions/_gh may require an administrator, and the manual's path may not exist on your distribution.
• Package updates: completion is generated from the installed gh. Regenerate the file after an upgrade if new commands or options do not appear.

Done means

• CLI confirmed. gh --version succeeds and matches the release you are documenting.
• Script in place. The completion script for your shell exists in the expected location.
• Tab works. A fresh shell offers gh subcommands when you press Tab.
• Nothing else touched. No unrelated startup or completion files were changed.