--- title: Configure the CLI stage: AI Clients group: Developer Clients info: To determine the technical writer assigned to the Stage/Group associated with this page, see --- {{< details >}} - Tier: Free, Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} By default, `glab` follows the [XDG Base Directory Spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), which means it searches for configuration files in multiple locations with proper precedence. ## Configuration levels Configure `glab` at different levels: system-wide, globally (per-user), locally (per-repository), or per host: - **System-wide** (for all users): Place configuration at `/etc/xdg/glab-cli/config.yml` (or `$XDG_CONFIG_DIRS/glab-cli/config.yml`). - Use this level for Linux distributions and system administrators to provide default configurations. - User configurations override system-wide settings. - **Globally** (per-user): run `glab config set --global editor vim`. - The global configuration file is available at `~/.config/glab-cli/config.yml` (or `$XDG_CONFIG_HOME/glab-cli/config.yml`). - To override this location, set the `GLAB_CONFIG_DIR` environment variable. - **The current repository**: run `glab config set editor vim` in any folder in a Git repository. - The local configuration file is available at `.git/glab-cli/config.yml` in the current working Git directory. - **Per host**: run `glab config set editor vim --host gitlab.example.org`, changing the `--host` parameter to meet your needs. - Per-host configuration information is always stored in the global configuration file, with or without the `global` flag. ## Configuration search order When `glab` looks for configuration files, it searches in this order (highest priority first): 1. `$GLAB_CONFIG_DIR/config.yml` (if `GLAB_CONFIG_DIR` is set) 1. `~/.config/glab-cli/config.yml` (legacy location, for backward compatibility) 1. `$XDG_CONFIG_HOME/glab-cli/config.yml` (platform-specific `XDG_CONFIG_HOME` location) 1. `$XDG_CONFIG_DIRS/glab-cli/config.yml` (system-wide configuration files, default: `/etc/xdg/glab-cli/config.yml`) The first configuration file found is used. ### Configuration file locations **For backward compatibility**, `glab` checks `~/.config/glab-cli/config.yml` first on all platforms. If no legacy configuration file exists, `glab` uses these platform-specific `XDG_CONFIG_HOME` locations: - **Linux**: `~/.config/glab-cli/config.yml` - **macOS**: `~/Library/Application Support/glab-cli/config.yml` - **Windows**: `%LOCALAPPDATA%\glab-cli\config.yml` > [!note] > If you have configuration files in both the legacy location (`~/.config/glab-cli/config.yml`) > and the platform-specific `XDG_CONFIG_HOME` location, `glab` uses the legacy location and > displays a warning. Consider consolidating to one location to avoid confusion. ## Environment variables Most configuration keys can also be set with an environment variable, which takes precedence over the value stored in the configuration file. Keys that take a list value, such as `custom_headers`, can be set only in the configuration file. Environment variables are a good fit for deploying a standard setup across an organization: set them centrally, and each user only authenticates. For more information, see [standardize setup across an organization](authentication.md#standardize-setup-across-an-organization). Environment variables are not scoped per host. A variable such as `GITLAB_API_HOST` applies to every host, so if you work with more than one GitLab instance, use the configuration file instead. Where a key lists more than one variable, `glab` uses the first one that is set. Some keys have both a `GLAB_`-prefixed variable and an unprefixed one. In those cases, the unprefixed name is kept for backward compatibility. Use the `GLAB_` form in new setups. For more information, see [issue 7999](https://gitlab.com/gitlab-org/cli/-/issues/7999). ### GitLab access variables | Variable | Configuration key | Default | Description | |----------|-------------------|---------|-------------| | `GITLAB_API_HOST` | `api_host` | `gitlab.com` | Configure host for API endpoint. Defaults to the host itself. | | `GITLAB_CLIENT_ID` | `client_id` | - | OAuth application client ID. Required when authenticating with OAuth against a self-managed GitLab instance. | | `GITLAB_GROUP` | - | - | Default group for commands that list merge requests, issues, and variables. Used only when `--group` is not given. | | `GITLAB_HEAD_REPO` | - | - | Source repository for `glab mr create`. Used only when `--head` is not given. | | `GITLAB_HOST` | `host` | `gitlab.com` | Default GitLab hostname to use. Inside a repository, a Git remote on another host takes precedence over the config key. A host from an environment variable, such as `GITLAB_HOST`, always wins, and glab errors if no remote matches it. | | `GITLAB_URI` | `host` | `gitlab.com` | Alternative name for `GITLAB_HOST`, checked after it. | | `GL_HOST` | `host` | `gitlab.com` | Alternative name for `GITLAB_HOST`, checked after it. | | `GITLAB_REPO` | - | - | Default repository for commands that accept `--repo`. Used only when `--repo` is not given. | | `GITLAB_SSH_HOST` | `ssh_host` | - | Alternate hostname for SSH Git operations (e.g., `ssh.example.com` or `git.example.com`). Use this when SSH uses a different hostname than HTTP/API operations. Only affects SSH cloning and Git operations. | | `GITLAB_SUBFOLDER` | `subfolder` | - | Subfolder where GitLab is installed (e.g., `gitlab` for ). Use this when GitLab is hosted at a subfolder rather than domain root. Supports nested paths (e.g., `apps/gitlab` for ). Slashes are automatically trimmed, so `gitlab`, `/gitlab`, and `gitlab/` are equivalent. Only applies to HTTP/HTTPS operations (API and Git clone). | | `GITLAB_TOKEN` | `token` | - | Your GitLab access token. To get one, read . A token set through an environment variable is sent only to the host named by `GITLAB_HOST` (or the `host` configuration key) or `GITLAB_REPO`, and to hosts already present in your configuration file. A host named only in a command argument receives no token. | | `GITLAB_ACCESS_TOKEN` | `token` | - | Alternative name for `GITLAB_TOKEN`, checked after it. | | `OAUTH_TOKEN` | `token` | - | Alternative name for `GITLAB_TOKEN`, checked after it. | | `GLAB_API_PROTOCOL` | `api_protocol` | `https` | What protocol to use to access the API endpoint. Supported values: `http`, `https`. | | `API_PROTOCOL` | `api_protocol` | `https` | Alternative name for `GLAB_API_PROTOCOL`, checked after it. | | `GLAB_ARTIFACT_REGISTRY_DOMAINS` | `artifact_registry_domains` | - | The domains of associated Artifact Registries. These are used to configure the Docker credential helper. Only list a domain here if it is actually backed by GitLab Artifact Registry: the credential helper tries this key first, and a successful token exchange is used as-is, with no fallback to container_registry_domains. A container-registry domain listed here by mistake gets an artifact-registry token the registry rejects, and `docker pull` hard-fails. | | `ARTIFACT_REGISTRY_DOMAINS` | `artifact_registry_domains` | - | Alternative name for `GLAB_ARTIFACT_REGISTRY_DOMAINS`, checked after it. | | `GLAB_CA_CERT` | `ca_cert` | - | Path to a CA certificate (PEM) used to verify the GitLab server's TLS certificate. glab dependency-firewall commands also trust it for package registries and outbound proxies. Useful for self-signed or private certificate authorities. | | `CA_CERT` | `ca_cert` | - | Alternative name for `GLAB_CA_CERT`, checked after it. | | `GLAB_CLIENT_CERT` | `client_cert` | - | Path to a client certificate used for mutual TLS authentication. Use a PEM or DER certificate with client_key, or a PKCS#12 bundle (.p12, .pfx) and leave client_key unset. glab dependency-firewall commands also present it to an https:// outbound proxy, never to package registries. | | `CLIENT_CERT` | `client_cert` | - | Alternative name for `GLAB_CLIENT_CERT`, checked after it. | | `GLAB_CLIENT_CERT_PASSWORD` | `client_cert_password` | - | Password that decrypts a PKCS#12 client_cert. Stored in the operating system's keyring when use_keyring is true. | | `GLAB_CLIENT_KEY` | `client_key` | - | Path to the private key (PEM or DER, in PKCS#8, PKCS#1, or EC format) that matches client_cert. Leave unset when client_cert is a PKCS#12 bundle. | | `CLIENT_KEY` | `client_key` | - | Alternative name for `GLAB_CLIENT_KEY`, checked after it. | | `GLAB_CONTAINER_REGISTRY_DOMAINS` | `container_registry_domains` | `gitlab.com,gitlab.com:443,registry.gitlab.com` | The domains of associated container registries. These are used to configure the Docker credential helper. | | `CONTAINER_REGISTRY_DOMAINS` | `container_registry_domains` | `gitlab.com,gitlab.com:443,registry.gitlab.com` | Alternative name for `GLAB_CONTAINER_REGISTRY_DOMAINS`, checked after it. | | `GLAB_ENABLE_CI_AUTOLOGIN` | - | `false` | Set to true to enable auto-login in GitLab CI. Together with `GITLAB_CI=true`, glab signs in using predefined CI/CD variables such as `CI_SERVER_FQDN` and `CI_JOB_TOKEN`, and ignores host variables such as `GITLAB_HOST`. | | `GLAB_PROXY` | `proxy` | - | Custom proxy for this host. Overrides environment proxy settings when set. | | `GLAB_SKIP_TLS_VERIFY` | `skip_tls_verify` | - | Skip TLS certificate verification when talking to this host (true/false). Empty is treated as false. Use only for development; do not enable in production. | | `SKIP_TLS_VERIFY` | `skip_tls_verify` | - | Alternative name for `GLAB_SKIP_TLS_VERIFY`, checked after it. | | `GLAB_USE_KEYRING` | `use_keyring` | - | Store the host's credentials in the operating system's keyring (true/false). Set automatically by `glab auth login`, which defaults to `true` when a keyring backend is available. Empty is treated as false (plaintext file storage). | | `USE_KEYRING` | `use_keyring` | - | Alternative name for `GLAB_USE_KEYRING`, checked after it. | ### `glab` configuration variables | Variable | Configuration key | Default | Description | |----------|-------------------|---------|-------------| | `FORCE_HYPERLINKS` | `display_hyperlinks` | - | Set to 1 to force terminal hyperlinks when not writing to a TTY. A falsy value falls through to `display_hyperlinks`. | | `GITLAB_RELEASE_ASSETS_USE_PACKAGE_REGISTRY` | - | - | Set to true or 1 to upload release assets to the generic package registry of the project. The `--use-package-registry` flag takes precedence. | | `GLAB_BRANCH_PREFIX` | `branch_prefix` | - | Prefix used by `glab stack` when naming generated branches. Defaults to the current user's username (from `os/user.Current`), falling back to `glab-stack` if unavailable. | | `BRANCH_PREFIX` | `branch_prefix` | - | Alternative name for `GLAB_BRANCH_PREFIX`, checked after it. | | `GLAB_BROWSER` | `browser` | - | What browser glab should run when opening links. This global config cannot be overridden by hostname. | | `BROWSER` | `browser` | - | Alternative name for `GLAB_BROWSER`, checked after it. | | `GLAB_CHECK_UPDATE` | `check_update` | `true` | Allow glab to automatically check for updates and notify you when there are new updates. Setting the environment variable to true also forces a check, bypassing the once-a-day interval. | | `CHECK_UPDATE` | `check_update` | `true` | Alternative name for `GLAB_CHECK_UPDATE`, checked after it. | | `GLAB_COLOR` | `color` | `auto` | Set whether glab colors its output. Available options are [auto, never, always]. `auto` detects whether the output is a terminal. This key takes precedence over the NO_COLOR environment variable; NO_COLOR applies when this is `auto` (or unset). | | `GLAB_CONFIG_DIR` | - | `~/.config/glab-cli` | Directory holding the global configuration file. Takes priority over the XDG locations. | | `GLAB_DEBUG` | `debug` | `false` | Output more logging information, including underlying Git commands, expanded aliases, and DNS error details. | | `GLAB_DEBUG_HTTP` | - | `false` | Set to true to output HTTP transport information (request and response). | | `GLAB_DISPLAY_HYPERLINKS` | `display_hyperlinks` | `true` | Whether or not to display hyperlinks in terminal output. Defaults to true (enabled for TTYs). Set to false to disable. Force hyperlinks in non-TTY environments by setting FORCE_HYPERLINKS=1. | | `DISPLAY_HYPERLINKS` | `display_hyperlinks` | `true` | Alternative name for `GLAB_DISPLAY_HYPERLINKS`, checked after it. | | `GLAB_DUO_CLI_AUTO_DOWNLOAD` | `duo_cli_auto_download` | - | Automatically download Duo CLI binary without prompting (true/false). | | `DUO_CLI_AUTO_DOWNLOAD` | `duo_cli_auto_download` | - | Alternative name for `GLAB_DUO_CLI_AUTO_DOWNLOAD`, checked after it. | | `GLAB_DUO_CLI_AUTO_RUN` | `duo_cli_auto_run` | - | Automatically run GitLab Duo CLI without prompting (true/false). Set to true to skip the confirmation prompt. | | `DUO_CLI_AUTO_RUN` | `duo_cli_auto_run` | - | Alternative name for `GLAB_DUO_CLI_AUTO_RUN`, checked after it. | | `GLAB_EDITOR` | `editor` | - | What editor glab should run when creating issues, merge requests, etc. This global config cannot be overridden by hostname. | | `VISUAL` | `editor` | - | Alternative name for `GLAB_EDITOR`, checked after it. | | `EDITOR` | `editor` | - | Alternative name for `GLAB_EDITOR`, checked after it. | | `GLAB_FORCE_HYPERLINKS` | `display_hyperlinks` | - | Set to true to force terminal hyperlinks when not writing to a TTY. | | `GLAB_GIT_PROTOCOL` | `git_protocol` | `ssh` | What protocol to use when performing Git operations. Supported values: `ssh`, `https`. | | `GIT_PROTOCOL` | `git_protocol` | `ssh` | Alternative name for `GLAB_GIT_PROTOCOL`, checked after it. | | `GLAB_GLAMOUR_STYLE` | `glamour_style` | `auto` | Set your desired Markdown renderer style. Available options are [auto, dark, light, notty]. `auto` detects your terminal's background color. To set a custom style, refer to . | | `GLAMOUR_STYLE` | `glamour_style` | `auto` | Alternative name for `GLAB_GLAMOUR_STYLE`, checked after it. | | `GLAB_MINDER_CLI_AUTO_DOWNLOAD` | `minder_cli_auto_download` | - | Automatically download the GitLab Endpoint Agent Platform binary without prompting (true/false). | | `MINDER_CLI_AUTO_DOWNLOAD` | `minder_cli_auto_download` | - | Alternative name for `GLAB_MINDER_CLI_AUTO_DOWNLOAD`, checked after it. | | `GLAB_MINDER_CLI_AUTO_RUN` | `minder_cli_auto_run` | - | Automatically run the GitLab Endpoint Agent Platform without prompting (true/false). Set to true to skip the confirmation prompt. | | `MINDER_CLI_AUTO_RUN` | `minder_cli_auto_run` | - | Alternative name for `GLAB_MINDER_CLI_AUTO_RUN`, checked after it. | | `GLAB_NOTIFY_SKILL_UPDATES` | `notify_skill_updates` | `true` | Show a notice when an installed agent skill (bundled or remote) has updates available. | | `GLAB_NO_PROMPT` | `no_prompt` | `false` | Set to true (1) to disable prompts, or false (0) to enable them. | | `NO_PROMPT` | `no_prompt` | `false` | Alternative name for `GLAB_NO_PROMPT`, checked after it. | | `PROMPT_DISABLED` | `no_prompt` | `false` | Alternative name for `GLAB_NO_PROMPT`, checked after it. | | `GLAB_ORBIT_CLI_AUTO_DOWNLOAD` | `orbit_cli_auto_download` | - | Automatically download the GitLab Orbit CLI binary without prompting (true/false). | | `ORBIT_CLI_AUTO_DOWNLOAD` | `orbit_cli_auto_download` | - | Alternative name for `GLAB_ORBIT_CLI_AUTO_DOWNLOAD`, checked after it. | | `GLAB_ORBIT_CLI_AUTO_RUN` | `orbit_cli_auto_run` | - | Automatically run the GitLab Orbit CLI without prompting (true/false). Set to true to skip the confirmation prompt. | | `ORBIT_CLI_AUTO_RUN` | `orbit_cli_auto_run` | - | Alternative name for `GLAB_ORBIT_CLI_AUTO_RUN`, checked after it. | | `GLAB_PAGER` | `glab_pager` | - | Your desired pager command to use, such as `less -R`. Takes precedence over the PAGER environment variable. GLAB_PAGER takes precedence over both. | | `GLAB_SEND_TELEMETRY` | `telemetry` | `true` | Set to false (0) to disable sending usage data to your GitLab instance or true (1) to enable. See for more information. | | `GLAB_SHOW_WHATS_NEW` | `show_whats_new` | `true` | Show a one-time post-upgrade banner pointing at `glab whatsnew` when a new version is detected. Not shown when standard error is not a terminal, or when `CI` or `GITLAB_CI` is true. Set `GLAB_SHOW_WHATS_NEW=false` to turn it off. | | `NO_COLOR` | - | - | Set to any value to avoid printing ANSI escape sequences for color output. | ### Other variables | Variable | Configuration key | Default | Description | |----------|-------------------|---------|-------------| | `GLAB_REMOTE_ALIAS` | `remote_alias` | - | Name of the `git remote` that points at the GitLab repository. Used to resolve which remote to operate against when multiple are configured. | | `GIT_REMOTE_URL_VAR` | `remote_alias` | - | Alternative name for `GLAB_REMOTE_ALIAS`, checked after it. | | `GIT_REMOTE_ALIAS` | `remote_alias` | - | Alternative name for `GLAB_REMOTE_ALIAS`, checked after it. | | `REMOTE_ALIAS` | `remote_alias` | - | Alternative name for `GLAB_REMOTE_ALIAS`, checked after it. | | `REMOTE_NICKNAME` | `remote_alias` | - | Alternative name for `GLAB_REMOTE_ALIAS`, checked after it. | | `GIT_REMOTE_NICKNAME` | `remote_alias` | - | Alternative name for `GLAB_REMOTE_ALIAS`, checked after it. |