GLab

GLab is an open source GitLab CLI tool. It brings GitLab to your terminal, next to where you are already working with git and your code, without switching between windows and browser tabs. While it's powerful for issues and merge requests, glab does even more:

• View, manage, and retry CI/CD pipelines directly from your CLI.
• Create changelogs.
• Create and manage releases.
• Ask GitLab Duo Chat (Classic) questions about Git.
• Manage GitLab agents for Kubernetes.

glab is available for repositories hosted on GitLab.com, GitLab Dedicated, and GitLab Self-Managed. It supports multiple authenticated GitLab instances, and automatically detects the authenticated hostname from the remotes available in your working Git directory.

Table of contents

• Requirements
• Usage
  • Commands
  • GitLab Duo for the CLI
• Demo
• Documentation
• Installation
  • Homebrew
  • Other installation methods
  • Building from source
    • Prerequisites for building from source
• Authentication
• Configuration
• Environment variables
  • GitLab access variables
  • glab configuration variables
  • Other variables
  • Token and environment variable precedence
  • Debugging
• Troubleshooting
• Issues
• Security
• Contributing
  • Versioning
  • Classify version changes
  • Compatibility
• Inspiration

Requirements

glab officially supports GitLab versions 16.0 and later. Certain commands might require more recent versions. While many commands might work properly in GitLab versions 15.x and earlier, no support is provided for these versions.

Usage

To get started with glab:

1. Follow the installation instructions appropriate for your operating system.
2. Authenticate into your instance of GitLab.
3. Optional. Configure glab further to meet your needs:
   • 1Password users can configure it to authenticate to glab.
   • Set any needed global, per-project, or per-host configuration.
   • Set any needed environment variables.

You're ready!

Commands

Run glab --help to view a list of core commands in your terminal.

• glab alias: Create, list, and delete aliases.
• glab api: Make an authenticated request to the GitLab API.
• glab artifact-registry: Authenticate with GitLab Artifact Registry. (EXPERIMENTAL)
• glab attestation: Manage software attestations. (EXPERIMENTAL)
• glab auth: Manage authentication for glab.
• glab changelog: Generate changelogs from your project's commit history.
• glab check-update: Check for the latest glab version.
• glab ci: Work with GitLab CI/CD pipelines and jobs.
• glab cluster: Manage GitLab Agents for Kubernetes and their clusters.
• glab completion: Generate shell completion scripts.
• glab config: Manage glab settings.
• glab container-registry: Work with GitLab container registries.
• glab dependency-firewall: Configure and monitor GitLab Dependency Firewall for local package managers. (EXPERIMENTAL)
• glab deploy-key: Manage deploy keys.
• glab duo: Work with GitLab Duo.
• glab gpg-key: Manage GPG keys registered with your GitLab account.
• glab incident: Work with GitLab incidents.
• glab issue: Work with GitLab issues.
• glab iteration: Retrieve iteration information.
• glab job: Work with GitLab CI/CD jobs.
• glab label: Manage project and group labels.
• glab mcp: Work with a Model Context Protocol (MCP) server. (EXPERIMENTAL)
• glab milestone: Manage group or project milestones.
• glab mr: Create, view, and manage merge requests.
• glab opentofu: Work with the OpenTofu or Terraform integration.
• glab orbit: GitLab Knowledge Graph commands. (EXPERIMENTAL)
• glab packages: Manage packages in the GitLab package registry.
• glab release: Manage GitLab releases.
• glab repo: Work with GitLab repositories and projects.
• glab runner: Manage GitLab CI/CD runners.
• glab runner-controller: Manage runner controllers. (EXPERIMENTAL)
• glab schedule: Work with GitLab CI/CD schedules.
• glab search: Search for code and resources in a GitLab project. (BETA)
• glab securefile: Manage secure files for a project.
• glab security: Manage GitLab security scan profiles for a project. (EXPERIMENTAL)
• glab skills: Manage glab agent skills. (EXPERIMENTAL)
• glab snippet: Create, view and manage snippets.
• glab ssh-key: Manage SSH keys registered with your GitLab account.
• glab stack: Create, manage, and work with stacked diffs. (EXPERIMENTAL)
• glab todo: Manage your to-do list.
• glab token: Manage personal, project, or group tokens.
• glab user: Interact with a GitLab user account.
• glab variable: Manage variables for a GitLab project or group.
• glab version: Show version information for glab.
• glab whatsnew: Show release notes for new versions of glab.
• glab work-items: Manage work items. (EXPERIMENTAL)

Commands follow this pattern:

glab <command> <subcommand> [flags]

Many core commands also have sub-commands. Some examples:

• List merge requests assigned to you: glab mr list --assignee=@me
• List review requests for you: glab mr list --reviewer=@me
• Approve a merge request: glab mr approve 235
• Create an issue, and add milestone, title, and label: glab issue create -m release-2.0.0 -t "My title here" --label important

GitLab Duo for the CLI

The GitLab CLI also includes support for using the GitLab Duo Agent Platform directly in your terminal.

Use glab duo cli to ask GitLab Duo questions about your codebase and to autonomously perform actions on your behalf.

For more information, see GitLab Duo CLI.

Demo

Documentation

Read the documentation for usage instructions or check out glab help.

Installation

Download a binary suitable for your OS at the releases page. Other installation methods depend on your operating system.

Homebrew

Homebrew is the officially supported package manager for macOS, Linux, and Windows (through Windows Subsystem for Linux)

• Homebrew
  • Install with: brew install glab
  • Update with: brew upgrade glab

Other installation methods

Other options to install the GitLab CLI that may not be officially supported or are maintained by the community are also available.

Building from source

If a supported binary for your OS is not found at the releases page, you can build from source:

Prerequisites for building from source

• make
• Go version as defined by main/go.mod

To build from source:

1. Run go version to verify that you have the minimum required Go version. If Go is not installed, see Download and install.
2. Clone the repository: git clone https://gitlab.com/gitlab-org/cli.git
3. Build the binary: make build
4. Install glab in $GOPATH/bin: make install
5. Optional. If $GOPATH/bin or $GOBIN is not in your $PATH, run export PATH=$PWD/bin:$PATH.
6. Confirm the installation: glab version

Authentication

To authenticate glab with OAuth, a personal access token, or a CI job token, see Authenticate with GitLab.

Configuration

For configuration levels, the configuration search order, and platform-specific file locations, see Configure the CLI.

For connecting to a GitLab Self-Managed or GitLab Dedicated instance, and for mTLS and self-signed certificates, see Connect to your GitLab instance.

For authenticating proxies, including custom HTTP headers and Google Identity-Aware Proxy, see Connect through a proxy.

Environment variables

GitLab access variables

Token name	In config.yml	Default value if not set	Description
GITLAB_ACCESS_TOKEN	hosts.<hostname>.token	-	An authentication token for API requests. Functionally equivalent to GITLAB_TOKEN. Checked after GITLAB_TOKEN and overrides any previously stored credentials.
GITLAB_API_HOST	hosts.<hostname>.api_host, or hosts.<hostname> if empty	Hostname found in the Git URL	Specify the host where the API endpoint is found. Useful when there are separate (sub)domains or hosts for Git and the API endpoint.
GITLAB_CLIENT_ID	hosts.<hostname>.client_id	Client-ID for GitLab.com.	A custom Client-ID generated by the GitLab OAuth 2.0 application.
GITLAB_GROUP	-	-	Default GitLab group used for listing merge requests, issues and variables. Only used if no --group option is given.
GITLAB_HOST	host (this is the default host glab will use when the current directory is not a git directory)	https://gitlab.com	Alias of GITLAB_URI.
GITLAB_REPO	-	-	Default GitLab repository used for commands accepting the --repo option. Only used if no --repo option is given.
GITLAB_TOKEN	hosts.<hostname>.token	-	An authentication token for API requests. Setting this avoids being prompted to authenticate and overrides any previously stored credentials. Can be set in the config with glab config set token xxxxxx.
GITLAB_URI	not applicable	not applicable	Alias of GITLAB_HOST.
OAUTH_TOKEN	hosts.<hostname>.token	-	An OAuth 2.0 authentication token for API requests. Checked after GITLAB_TOKEN and GITLAB_ACCESS_TOKEN, and overrides any previously stored credentials. On a host configured with is_oauth2: true, glab continues to use the OAuth 2.0 refresh flow.

glab configuration variables

Token name	In config.yml	Default value if not set	Description
BROWSER	browser	system default	The web browser to use for opening links. Can be set in the configuration with glab config set browser mybrowser.
GITLAB_RELEASE_ASSETS_USE_PACKAGE_REGISTRY	-	-	When true or 1, the glab release create command uploads release assets to the generic package registry of the project. Can be overridden with the --use-package-registry flag.
GLAB_CHECK_UPDATE	-	-	Set to true to force an update check.
GLAB_CONFIG_DIR	-	~/.config/glab-cli/	Directory where the glab global configuration file is located. Can be set in the config with glab config set remote_alias origin.
GLAB_DEBUG	debug	false	Set to true to output more information for each command, like Git commands, expanded aliases, and DNS error details.
GLAB_DEBUG_HTTP	-	false	Set to true to output HTTP transport information (request / response).
GLAB_FORCE_HYPERLINKS	display_hyperlinks	auto	Set to true (or any truthy value) to force hyperlinks even when not outputting to a TTY. A falsy value falls through to display_hyperlinks.
GLAB_GLAMOUR_STYLE	glamour_style	dark	Environment variable to set your desired Markdown renderer style. Available options are (dark, light, notty) or set a custom style.
GLAB_NO_PROMPT	no_prompt	false	Set to true to disable prompts.
GLAB_SEND_TELEMETRY	telemetry	true	Set to false to prevent command usage data from being sent to your GitLab instance.
NO_COLOR	-	true	Set to any value to avoid printing ANSI escape sequences for color output.
VISUAL, EDITOR	editor	nano	(in order of precedence) The editor tool to use for authoring text. Can be set in the config with glab config set editor vim.

Other variables

Token name	In config.yml	Default value if not set	Description
GIT_REMOTE_URL_VAR	not applicable	not applicable	Alias of REMOTE_ALIAS.
REMOTE_ALIAS	remote_alias	-	git remote variable or alias that contains the GitLab URL. Alias: GIT_REMOTE_URL_VAR

Variable deprecation

In glab version 2.0.0 and later, all glab environment variables are prefixed with GLAB_. For more information about this deprecation, see issue 7999.

Token and environment variable precedence

For every authenticated command, glab resolves the token to use in this order:

1. If any of these environment variables are defined, including in a CI/CD environment, glab uses the first available, in this order:
   • GITLAB_TOKEN
   • GITLAB_ACCESS_TOKEN
   • OAUTH_TOKEN
2. The credentials stored for the host, in the configuration file ($HOME/.config/glab-cli/config.yml) or in your operating system's keyring. glab auth login and glab config set token write them there.
3. If CI/CD auto-login is enabled (GLAB_ENABLE_CI_AUTOLOGIN=true and GITLAB_CI=true), then glab uses a CI/CD job token (CI_JOB_TOKEN). If you need to use a job token, make sure the other variables are not set in the CI/CD job.

If no token is found, glab sends the request unauthenticated.

Note

Do not set GITLAB_TOKEN=$CI_JOB_TOKEN in a CI/CD job. glab makes API calls with GITLAB_TOKEN as an access token in the PRIVATE-TOKEN header, which does not accept CI/CD job tokens. Requests fail with 401 Unauthorized or 404 Not Found on endpoints that support job tokens.

Debugging

When the GLAB_DEBUG environment variable is set to true, glab outputs more logging information, including:

• Underlying Git commands.
• Expanded aliases.
• DNS error details.

Troubleshooting

For help with common authentication issues, see Troubleshooting in the GitLab CLI documentation.

Issues

If you have an issue: report it on the issue tracker

Security

To report a security vulnerability in glab, follow the process in the security policy. Please do not open a public issue.

To learn how the project handles dependency updates and container-scanner CVE reports, see dependency management and reporting a vulnerability in CONTRIBUTING.md.

Contributing

Feel like contributing? That's awesome! We have a contributing guide and Code of conduct to help guide you.

When updating command help text or documentation, follow the GitLab CLI documentation style guide.

Versioning

This project follows the SemVer specification.

Classify version changes

• If deleting a command, changing how it behaves, or adding a new required flag, the release must use a new MAJOR revision.
• If adding a new command or optional flag, the release must use a new MINOR revision.
• If fixing a bug, the release must use a new PATCH revision.

Compatibility

We do our best to introduce breaking changes only when releasing a new MAJOR version. Unfortunately, there are situations where this is not possible, and we may introduce a breaking change in a MINOR or PATCH version. Some of situations where we may do so:

• If a security issue is discovered, and the solution requires a breaking change, we may introduce such a change to resolve the issue and protect our users.
• If a feature was not working as intended, and the bug fix requires a breaking change, the bug fix may be introduced to ensure the functionality works as intended.
• When feature behavior is overwhelmingly confusing due to a vague specification on how it should work. In such cases, we may refine the specification to remove the ambiguity, and introduce a breaking change that aligns with the refined specification. For an example of this, see merge request 1382.
• Experimental features are not guaranteed to be stable, and can be modified or removed without a breaking change.

Breaking changes are a last resort, and we try our best to only introduce them when absolutely necessary.

Inspiration

The GitLab CLI was adopted from Clement Sam in 2022 to serve as the official CLI of GitLab. Over the years the project has been inspired by both the GitHub CLI and Zaq? Wiedmann's lab.

Lab has served as the foundation for many of the GitLab CI/CD commands including ci view and ci trace.