With the GitHub CLI, how do gh config settings and gh alias set work, and when does an alias need --shell?
answer
- config.yml beside hosts.yml
- global value, per-host override
- aliases cannot shadow commands
- $1 placeholders
- a leading exclamation mark
basics
~20 sgh 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 sgh 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 linesgh 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 disabledgo deeper
Recall gh config set for preferences like git_protocol or editor and gh alias set for shortcuts such as pv for pr view.
Explain global against per-host settings, how $1 placeholders and appended arguments work, and why a pipe needs --shell or a leading exclamation mark.
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.
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.