Configuration

On-disk layout

gh reads two YAML files plus the OS keyring. The directory is $GH_CONFIG_DIR if set, otherwise ~/.config/gh.

File	Purpose
config.yml	User-level preferences (git_protocol, editor, prompt, pager, aliases, accessible, telemetry, ...).
hosts.yml	Per-host auth state: active user, git_protocol, OAuth scopes, optional token.
OS keyring	Tokens are persisted here when the OS supports it (Keychain on macOS, libsecret on Linux, wincred on Windows).

The structures and accessors live in internal/config/config.go. Multi-account behaviour is documented in docs/multiple-accounts.md.

Configuration keys

The most commonly used keys (set with gh config set <key> <value>):

Key	Description	Default
git_protocol	Default protocol for clone URLs (https or ssh).	https
editor	Editor used for body composition.	git config core.editor or $VISUAL / $EDITOR
prompt	enabled or disabled.	enabled
pager	Pager command.	less -FRX
accessible	Accessibility preset (enabled/disabled/screen-reader).	disabled
aliases	User-defined CLI aliases.	empty
telemetry	enabled / disabled / log.	enabled (with GHES heuristic skip)
browser	Browser used by gh browse and OAuth flow.	OS default
version	Internal config schema version.	managed by migration

hosts.yml keys (per host):

Key	Description
users	Map of accounts; each account stores oauth_token, git_protocol, user.
user	The currently active user for this host.

Environment variables

gh help environment prints the canonical list. The most relevant for development:

Variable	Effect
GH_TOKEN / GITHUB_TOKEN	Fixed token, takes precedence over config.
GH_HOST	Pin the default host (e.g. github.example.com).
GH_CONFIG_DIR	Override config directory.
GH_DEBUG=api	Print HTTP traffic.
GH_DEBUG=true	General debug logging.
GH_PAGER / PAGER	Pager.
GH_BROWSER / BROWSER	Browser.
GH_PROMPT_DISABLED	Force non-interactive.
NO_COLOR / CLICOLOR / CLICOLOR_FORCE	Color toggles.
GH_NO_UPDATE_NOTIFIER	Skip update check.
GH_FORCE_TTY=<width>	Pretend stdout is a TTY of N columns.
AI_AGENT, AGENT, CLAUDECODE, CODEX_*, COPILOT_CLI, GEMINI_CLI, OPENCODE	Agent detection signals (see internal/agents/detect.go).
GH_REPO	Override BaseRepo for one invocation.

Per-extension config

Extensions can persist their own state under $GH_CONFIG_DIR/extensions/gh-<name>/. The path is conventional, not enforced; extension authors typically nest their own files there.

Related pages

• Auth and config command.
• Config and auth (system view).