gh-environment

Display help about environment variables that can be used with gh

$ gh environment

gh env [VARIABLE]
gh env VARIABLE=VALUE
gh env --unset VARIABLE

VARIABLE
    When used without a value, displays the current value of the specified GitHub CLI environment variable. If no VARIABLE is provided, lists all known GitHub CLI environment variables and their values.

VARIABLE=VALUE
    Sets the specified GitHub CLI environment variable to the given VALUE. This change is typically persistent across sessions.

--unset VARIABLE
    Removes (unsets) the specified GitHub CLI environment variable from the configuration. This change is also typically persistent.

-h, --help
    Displays help information for the gh env command.

The gh env command, also known as gh environment, is a powerful utility within the GitHub CLI tool used to inspect, set, and unset environment variables that influence gh's behavior.

Unlike typical shell environment variables set with export, changes made via gh env are generally persistent, stored within gh's configuration files (e.g., ~/.config/gh/config.yml or ~/.config/gh/hosts.yml). This ensures that settings like authentication tokens (GH_TOKEN), the GitHub host (GH_HOST), or preferred pager (GH_PAGER) are maintained across shell sessions.

It provides a centralized and persistent way to configure the GitHub CLI, making it easier to manage credentials, preferred behaviors, and connectivity settings.

Changes made by gh env are written to gh's configuration files and are generally persistent, not just for the current shell session. Be cautious when setting sensitive information like GH_TOKEN as it will be stored in plain text (though protected by file permissions). This command manages only gh-specific environment variables and not general shell environment variables.

Unlike traditional shell export commands, which only affect the current shell session, gh env writes its changes to gh's configuration files (e.g., ~/.config/gh/config.yml or ~/.config/gh/hosts.yml). This means settings applied via gh env will persist across new shell sessions and system reboots, ensuring consistent gh behavior.

Some frequently used GitHub CLI environment variables that can be managed with gh env include:

• GH_TOKEN: The GitHub authentication token.
• GH_HOST: The GitHub host to interact with (e.g., github.com or an enterprise instance).
• GH_PAGER: Specifies the pager program for long output.
• GH_EDITOR: Specifies the editor program for interactive prompts.
• GH_DEBUG: Enables debug logging.

gh env (or gh environment) was introduced in GitHub CLI version 2.0.0, released in 2021. Its addition aimed to provide a standardized, persistent, and centralized way to manage gh-specific environment variables, moving away from relying solely on shell-level export commands for critical gh configurations.

gh(1), gh-config(1), env(1), printenv(1)