skip to content

With the GitHub CLI, how do gh config settings and gh alias set work, and when does an alias need --shell?

level: middleimportance: nice to knowfreq 14%

answer

  1. config.yml beside hosts.yml
  2. global value, per-host override
  3. aliases cannot shadow commands
  4. $1 placeholders
  5. a leading exclamation mark

basics

~20 s

gh config set writes settings such as git_protocol, editor, pager and prompt, globally or per host with --host. gh alias set maps a word to a gh command; it needs --shell, or a leading !, to pipe through sh.

solid answer

~50 s

gh keeps settings in `config.yml` in its config directory (`GH_CONFIG_DIR` when set), with per-host values stored under that host in `hosts.yml`. `gh config set <key> <value>` writes a global value, `--host` a per-host one that wins for that host; `gh config get` reads back the effective value. Known keys include `git_protocol` (default `https`, or `ssh`), `editor`, `pager`, `prompt` (`enabled`/`disabled`), `browser` and `http_unix_socket`; since gh 2.101.0 `clipboard`, global only, defaults to `enabled` so device codes are copied automatically. `gh alias set pv 'pr view'` creates a shortcut; extra arguments are appended or fill `$1`-style placeholders. The name may not be an existing gh command or extension, and replacing an alias needs `--clobber`. A plain expansion must start with a gh command, extension or alias; `--shell` (or a leading `!`) runs it through `sh`, which allows pipes and other programs, so the expansion must call `gh` itself.

code

bash · 6 lines
bash
gh alias set mine 'pr list --author "@me"'
gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
gh igrep bug timeout   # sh runs: gh issue list --label="bug" | grep "timeout"
gh config set git_protocol ssh --host ghe.example.com
gh config get git_protocol --host ghe.example.com   # ssh
gh config set prompt disabled

go deeper

for a junior

Recall gh config set for preferences like git_protocol or editor and gh alias set for shortcuts such as pv for pr view.

for a middle

Explain global against per-host settings, how $1 placeholders and appended arguments work, and why a pipe needs --shell or a leading exclamation mark.

for a senior

Show care with shared setups: catch silently accepted unknown keys, treat shell aliases as scripts that run arbitrary commands, and prefer environment variables in CI.

for a principal

Decide what belongs in personal gh configuration and what belongs in versioned team scripts or extensions, so team workflows do not depend on each person's aliases.

## Where gh keeps its settings The GitHub CLI stores its configuration in its **config directory**: `GH_CONFIG_DIR` when set, otherwise `$XDG_CONFIG_HOME/gh`, `$AppData/GitHub CLI` on Windows, or `$HOME/.config/gh`. Two files matter: - `config.yml` — global settings and the `aliases` map. - `hosts.yml` — one entry per host gh has logged in to: its accounts, the active account and **per-host settings** such as `git_protocol`. ## `gh config set` and `get` `gh config set <key> <value>` writes a value; `--host <hostname>` writes it for one host only. When gh reads a setting for a host it takes the per-host value first, then the global value, then the built-in default, and `gh config get <key>` (with `--host` for a host) shows the result. `gh config list` prints the current values. | Key | What it controls | Default and values | |---|---|---| | `git_protocol` | protocol for Git clone and push operations gh performs | `https` (or `ssh`) | | `editor` | editor for authoring text, such as a pull request body | empty by default | | `pager` | program that receives standard output | empty, so the environment decides; `cat` disables paging | | `prompt` | interactive prompting in the terminal | `enabled` (or `disabled`) | | `browser` | browser for opening URLs | empty by default | | `clipboard` | copying one-time OAuth device codes to the clipboard | `enabled` (or `disabled`); global only | Two validation rules are worth knowing. An **unknown key** prints a warning that it is not a known configuration key, but is still written, so a typo can silently do nothing. A **known key with a fixed set of values** rejects anything else and lists the valid values. Some keys also have a scope: `clipboard` refuses `--host`, and `api_host` (an experimental per-host gateway setting) requires it. Environment variables cover the same ground for a single shell or job — `GH_EDITOR`, `GH_PAGER`, `GH_BROWSER` and `GH_PROMPT_DISABLED` among them — which suits CI better than editing a config file. ## `gh alias set` An alias is a word that expands to a gh command, stored in `config.yml`: 1. **Simple expansion.** `gh alias set pv 'pr view'` makes `gh pv -w 123` run `gh pr view -w 123`; arguments after the alias are appended. 2. **Placeholders.** `gh alias set epicsBy 'issue list --author="$1" --label="epic"'` puts the first argument where `$1` stands instead of appending it. 3. **Shell expansion.** With `--shell`, or an expansion that starts with `!`, the expansion is a shell expression evaluated by `sh`. That allows pipes, redirection and other programs, and it means the expansion must call `gh` explicitly. Rules the command enforces: - The alias **name may not be an existing gh command or extension**; gh refuses with "already a gh command or extension". A name can add a new subcommand under a command group, such as `'issue mine'`. - Reusing an existing alias name needs `--clobber`. - A non-shell expansion must correspond to a gh command, extension or alias; anything else is rejected. - `-` as the expansion reads it from standard input, which avoids quoting trouble. - `gh alias list` shows the aliases and `gh alias delete` removes one. ## When to choose which - Use a **plain alias** for a shortened gh command with fixed flags: it stays portable, cannot run arbitrary programs and gets gh's own argument handling. - Use a **shell alias** only when you need a pipeline or a second program. It runs whatever the expansion says through `sh`, so it depends on gh finding a `sh` (an issue on Windows machines without one), and it deserves the same review as any script. - For repeatable settings across a team, prefer environment variables in shared scripts to asking everyone to edit their own `config.yml`. ## Settings that matter in scripts A script or CI job usually wants gh never to stop and wait. `prompt` set to `disabled`, or `GH_PROMPT_DISABLED` in the environment, makes commands that would ask a question fail instead of hanging; pass the answer as a flag. `pager` set to `cat`, or `GH_PAGER=cat`, stops long output from being sent to an interactive pager. Neither changes authentication: the token still comes from `GH_TOKEN` or a stored login, whatever the configuration says.

  • How can an alias add a new subcommand under an existing gh command group?
    Give the alias a two-word name whose first word is a command group: `gh alias set 'issue mine' 'issue list --mention @me'` makes `gh issue mine` work. gh accepts it because `issue` itself is only a group and `mine` is not one of its commands; a name that matches an existing subcommand is refused.
  • What happens if you mistype a key in gh config set?
    gh warns that the key is not a known configuration key but still writes it, so nothing changes in behaviour and the typo sits in `config.yml`. Check with `gh config list` or `gh config get`; only known keys with fixed values are rejected outright.

  • gh aliases can redefine built-in commands such as pr
  • A shell alias can omit gh because gh prefixes it automatically
  • gh config set rejects every key it does not know
  • A global git_protocol always beats the per-host value
  • gh aliases live in Git's config alongside git aliases

Assumes gh 2.102; the clipboard key and its enabled default, which copies OAuth device codes during gh auth login and refresh, arrived in gh 2.101.0.