GitLabgitlab-org

cli

main
ply5 git calls12 ms100 KiB3 cachedprotocol v2
282 lines14 KiBRaw

GLab

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.

command example

Table of contents

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:

You're ready!

Commands

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

Commands follow this pattern:

shell
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

![asciicast](https://asciinema.org/a/368622.svg)

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, at the version in go.mod or later. Official releases build with the version in .tool-versions.

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

glab reads its configuration from environment variables as well as the configuration file. Every configuration key has a matching variable, and the variable wins over the stored value. Setting them centrally is a good way to give everyone in an organization the same setup.

For the full reference, see Environment variables. For how glab picks which token to use, see Token precedence.

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.

1# GLab
3![GLab](docs/source/img/glab-logo.png)
5GLab 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:
7- View, manage, and retry CI/CD pipelines directly from your CLI.
8- Create changelogs.
9- Create and manage releases.
10- Ask GitLab Duo Chat (Classic) questions about Git.
11- Manage GitLab agents for Kubernetes.
13`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.
15![command example](docs/source/img/getting-started.gif)
17## Table of contents
19- [Requirements](#requirements)
20- [Usage](#usage)
21 - [Commands](#commands)
22 - [GitLab Duo for the CLI](#gitlab-duo-for-the-cli)
23- [Demo](#demo)
24- [Documentation](#documentation)
25- [Installation](#installation)
26 - [Homebrew](#homebrew)
27 - [Other installation methods](#other-installation-methods)
28 - [Building from source](#building-from-source)
29 - [Prerequisites for building from source](#prerequisites-for-building-from-source)
30- [Authentication](#authentication)
31- [Configuration](#configuration)
32- [Environment variables](#environment-variables)
33 - [Debugging](#debugging)
34- [Troubleshooting](#troubleshooting)
35- [Issues](#issues)
36- [Security](#security)
37- [Contributing](#contributing)
38 - [Versioning](#versioning)
39 - [Classify version changes](#classify-version-changes)
40 - [Compatibility](#compatibility)
41- [Inspiration](#inspiration)
43## Requirements
45`glab` officially supports GitLab versions 16.0 and later. Certain commands might require
46more recent versions. While many commands might work properly in GitLab versions
4715.x and earlier, no support is provided for these versions.
49## Usage
51To get started with `glab`:
531. Follow the [installation instructions](#installation) appropriate for your operating system.
541. [Authenticate](#authentication) into your instance of GitLab.
551. Optional. Configure `glab` further to meet your needs:
56 - 1Password users can configure it to [authenticate to `glab`](https://developer.1password.com/docs/cli/shell-plugins/gitlab/).
57 - Set any needed global, per-project, or per-host [configuration](#configuration).
58 - Set any needed [environment variables](#environment-variables).
60You're ready!
62### Commands
64Run `glab --help` to view a list of core commands in your terminal.
66<!-- commands-list-start: generated by 'make gen-docs'; do not edit by hand -->
67- [`glab alias`](docs/source/alias): Create, list, and delete aliases.
68- [`glab api`](docs/source/api): Make an authenticated request to the GitLab API.
69- [`glab artifact-registry`](docs/source/artifact-registry): Authenticate with GitLab Artifact Registry. (EXPERIMENTAL)
70- [`glab attestation`](docs/source/attestation): Manage software attestations. (EXPERIMENTAL)
71- [`glab auth`](docs/source/auth): Manage authentication for glab.
72- [`glab changelog`](docs/source/changelog): Generate changelogs from your project's commit history.
73- [`glab check-update`](docs/source/check-update): Check for the latest glab version.
74- [`glab ci`](docs/source/ci): Work with GitLab CI/CD pipelines and jobs.
75- [`glab cluster`](docs/source/cluster): Manage GitLab Agents for Kubernetes and their clusters.
76- [`glab completion`](docs/source/completion): Generate shell completion scripts.
77- [`glab config`](docs/source/config): Manage glab settings.
78- [`glab container-registry`](docs/source/container-registry): Work with GitLab container registries.
79- [`glab dependency-firewall`](docs/source/dependency-firewall): Configure and monitor GitLab Dependency Firewall for local package managers. (BETA)
80- [`glab deploy-key`](docs/source/deploy-key): Manage deploy keys.
81- [`glab deploy-token`](docs/source/deploy-token): Manage deploy tokens.
82- [`glab duo`](docs/source/duo): Work with GitLab Duo.
83- [`glab gpg-key`](docs/source/gpg-key): Manage GPG keys registered with your GitLab account.
84- [`glab incident`](docs/source/incident): Work with GitLab incidents.
85- [`glab issue`](docs/source/issue): Work with GitLab issues.
86- [`glab iteration`](docs/source/iteration): Retrieve iteration information.
87- [`glab job`](docs/source/job): Work with GitLab CI/CD jobs.
88- [`glab label`](docs/source/label): Manage project and group labels.
89- [`glab milestone`](docs/source/milestone): Manage group or project milestones.
90- [`glab minder`](docs/source/minder): Manage AI governance and run the GitLab Endpoint Agent Platform. (EXPERIMENTAL)
91- [`glab mr`](docs/source/mr): Create, view, and manage merge requests.
92- [`glab opentofu`](docs/source/opentofu): Work with the OpenTofu or Terraform integration.
93- [`glab orbit`](docs/source/orbit): Query the GitLab Orbit context graph. (EXPERIMENTAL)
94- [`glab packages`](docs/source/packages): Manage packages in the GitLab package registry.
95- [`glab release`](docs/source/release): Manage GitLab releases.
96- [`glab repo`](docs/source/repo): Work with GitLab repositories and projects.
97- [`glab runner`](docs/source/runner): Manage GitLab CI/CD runners.
98- [`glab runner-controller`](docs/source/runner-controller): Manage runner controllers. (EXPERIMENTAL)
99- [`glab schedule`](docs/source/schedule): Work with GitLab CI/CD schedules.
100- [`glab search`](docs/source/search): Search for code and resources in a GitLab project. (BETA)
101- [`glab securefile`](docs/source/securefile): Manage secure files for a project.
102- [`glab security`](docs/source/security): Manage GitLab security scan profiles for a project. (EXPERIMENTAL)
103- [`glab service-account`](docs/source/service-account): Manage service accounts.
104- [`glab skills`](docs/source/skills): Manage glab agent skills. (EXPERIMENTAL)
105- [`glab snippet`](docs/source/snippet): Create snippets.
106- [`glab ssh-key`](docs/source/ssh-key): Manage SSH keys registered with your GitLab account.
107- [`glab stack`](docs/source/stack): Create, manage, and work with stacked diffs. (EXPERIMENTAL)
108- [`glab timelog`](docs/source/timelog): Report on time logged on issues and merge requests.
109- [`glab todo`](docs/source/todo): Manage your to-do list.
110- [`glab token`](docs/source/token): Manage personal, project, or group tokens.
111- [`glab user`](docs/source/user): Interact with a GitLab user account.
112- [`glab variable`](docs/source/variable): Manage variables for a GitLab project or group.
113- [`glab version`](docs/source/version): Show version information for glab.
114- [`glab whatsnew`](docs/source/whatsnew): Show release notes for new versions of glab.
115- [`glab work-items`](docs/source/work-items): Manage work items. (EXPERIMENTAL)
116<!-- commands-list-end -->
118Commands follow this pattern:
120```shell
121glab <command> <subcommand> [flags]
122```
124Many core commands also have sub-commands. Some examples:
126- List merge requests assigned to you: `glab mr list --assignee=@me`
127- List review requests for you: `glab mr list --reviewer=@me`
128- Approve a merge request: `glab mr approve 235`
129- Create an issue, and add milestone, title, and label: `glab issue create -m release-2.0.0 -t "My title here" --label important`
131### GitLab Duo for the CLI
133The GitLab CLI also includes support for using the GitLab Duo Agent Platform directly in your terminal.
135Use `glab duo cli` to ask GitLab Duo questions about your codebase and to autonomously perform actions on your behalf.
137For more information, see [GitLab Duo CLI](https://docs.gitlab.com/user/gitlab_duo_cli/).
139## Demo
141[![asciicast](https://asciinema.org/a/368622.svg)](https://asciinema.org/a/368622)
143## Documentation
145Read the [documentation](docs/source/_index.md) for usage instructions or check out `glab help`.
147## Installation
149Download a binary suitable for your OS at the [releases page](https://gitlab.com/gitlab-org/cli/-/releases).
150Other installation methods depend on your operating system.
152### Homebrew
154Homebrew is the officially supported package manager for macOS, Linux, and Windows (through [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install))
156- Homebrew
157 - Install with: `brew install glab`
158 - Update with: `brew upgrade glab`
160### Other installation methods
162Other options to install the GitLab CLI that may not be officially supported or are maintained by the community are [also available](docs/installation_options.md).
164### Building from source
166If a supported binary for your OS is not found at the [releases page](https://gitlab.com/gitlab-org/cli/-/releases), you can build from source:
168#### Prerequisites for building from source
170- `make`
171- Go, at the version in [`go.mod`](https://gitlab.com/gitlab-org/cli/-/blob/main/go.mod?ref_type=heads#L3) or later.
172 Official releases build with the version in [`.tool-versions`](https://gitlab.com/gitlab-org/cli/-/blob/main/.tool-versions).
174To build from source:
1761. Run `go version` to verify that you have the minimum required Go version.
177 If Go is not installed, see [Download and install](https://go.dev/doc/install).
1781. Clone the repository: `git clone https://gitlab.com/gitlab-org/cli.git`
1791. Build the binary: `make build`
1801. Install `glab` in `$GOPATH/bin`: `make install`
1811. Optional. If `$GOPATH/bin` or `$GOBIN` is not in your `$PATH`,
182 run `export PATH=$PWD/bin:$PATH`.
1831. Confirm the installation: `glab version`
185## Authentication
187To authenticate `glab` with OAuth, a personal access token, or a CI job token, see
188[Authenticate with GitLab](https://docs.gitlab.com/cli/authentication/).
190## Configuration
192For configuration levels, the configuration search order, and platform-specific file
193locations, see [Configure the CLI](https://docs.gitlab.com/cli/configuration/).
195For connecting to a GitLab Self-Managed or GitLab Dedicated instance, and for mTLS and
196self-signed certificates, see
197[Connect to your GitLab instance](https://docs.gitlab.com/cli/connection/).
199For authenticating proxies, including custom HTTP headers and Google Identity-Aware
200Proxy, see [Connect through a proxy](https://docs.gitlab.com/cli/proxies/).
202## Environment variables
204`glab` reads its configuration from environment variables as well as the configuration
205file. Every configuration key has a matching variable, and the variable wins over the
206stored value. Setting them centrally is a good way to give everyone in an organization
207the same setup.
209For the full reference, see
210[Environment variables](https://docs.gitlab.com/cli/configuration/#environment-variables).
211For how `glab` picks which token to use, see
212[Token precedence](https://docs.gitlab.com/cli/authentication/#token-precedence).
214### Debugging
216When the `GLAB_DEBUG` environment variable is set to `true`, `glab` outputs more logging information, including:
218- Underlying Git commands.
219- Expanded aliases.
220- DNS error details.
222## Troubleshooting
224For help with common authentication issues, see
225[Troubleshooting](https://docs.gitlab.com/cli/authentication/#troubleshooting) in the GitLab CLI documentation.
227## Issues
229If you have an issue: report it on the [issue tracker](https://gitlab.com/gitlab-org/cli/-/issues)
231## Security
233To report a security vulnerability in `glab`, follow the process in
234the [security policy](SECURITY.md). Please do not open a public issue.
236To learn how the project handles dependency updates and container-scanner CVE
237reports, see [dependency management](CONTRIBUTING.md#dependency-management)
238and [reporting a vulnerability](CONTRIBUTING.md#reporting-a-vulnerability)
239in `CONTRIBUTING.md`.
241## Contributing
243Feel like contributing? That's awesome! We have a [contributing guide](https://gitlab.com/gitlab-org/cli/-/blob/main/CONTRIBUTING.md) and [Code of conduct](https://about.gitlab.com/community/contribute/code-of-conduct/) to help guide you.
245When updating command help text or documentation, follow the
246[GitLab CLI documentation style guide](https://docs.gitlab.com/development/documentation/cli_styleguide/).
248### Versioning
250This project follows the [SemVer](https://github.com/semver/semver) specification.
252### Classify version changes
254- If deleting a command, changing how it behaves, or adding a new **required** flag, the release must use a new `MAJOR` revision.
255- If adding a new command or **optional** flag, the release must use a new `MINOR` revision.
256- If fixing a bug, the release must use a new `PATCH` revision.
258### Compatibility
260We do our best to introduce breaking changes only when releasing a new `MAJOR` version.
261Unfortunately, there are situations where this is not possible, and we may introduce
262a breaking change in a `MINOR` or `PATCH` version. Some of situations where we may do so:
264- If a security issue is discovered, and the solution requires a breaking change,
265 we may introduce such a change to resolve the issue and protect our users.
266- If a feature was not working as intended, and the bug fix requires a breaking change,
267 the bug fix may be introduced to ensure the functionality works as intended.
268- When feature behavior is overwhelmingly confusing due to a vague specification
269 on how it should work. In such cases, we may refine the specification
270 to remove the ambiguity, and introduce a breaking change that aligns with the
271 refined specification. For an example of this, see
272 [merge request 1382](https://gitlab.com/gitlab-org/cli/-/merge_requests/1382#note_1686888887).
273- Experimental features are not guaranteed to be stable, and can be modified or
274 removed without a breaking change.
276Breaking changes are a last resort, and we try our best to only introduce them when absolutely necessary.
278## Inspiration
280The GitLab CLI was adopted from [Clement Sam](https://gitlab.com/profclems) in 2022 to serve as the official CLI of GitLab. Over the years the project has been inspired by both the [GitHub CLI](https://github.com/cli/cli) and [Zaq? Wiedmann's](https://gitlab.com/zaquestion) [lab](https://github.com/zaquestion/lab).
282Lab has served as the foundation for many of the GitLab CI/CD commands including `ci view` and `ci trace`.
Diagnostics5 git calls · 12 ms
CallStatusSizeTime012 ms
discover200185 B5 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetch2005.0 KiB · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=5077
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.wants=e81520c865edb5b5edc060eb453a7f0af400273a
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5077
git.pkt.payload.max=5050
git.sideband.band1.bytes=5050
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e108d77fe6910d
Request
36aec5b7…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format