GLab

GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with git and your code without switching between windows and browser tabs. Work with issues, merge requests, watch running pipelines directly from your CLI among other features. Inspired by [gh], the official GitHub CLI tool.

glab is available for repositories hosted on GitLab.com and self-managed GitLab Instances. glab supports multiple authenticated GitLab instances and automatically detects the authenticated hostname from the remotes available in the working git directory.

Table of Contents

• Usage
• Demo
• Documentation
• Installation
  • Quick Install
  • Windows
    • WinGet
    • Scoop
    • EXE Installer
  • Linux
    • Linuxbrew (Homebrew)
    • Snapcraft
    • Arch Linux
    • KISS Linux
    • Alpine Linux
      • Install a pinned version from edge
      • Alpine Linux Docker-way
    • Nix/NixOS
  • macOS
    • Homebrew
    • MacPorts
  • Building From Source
    • Prerequisites
• Authentication
• Configuration
• Usage
• Environment Variables
• What about lab
• Issues
• Contributing
  • Support glab 💖
    • Individuals
    • Backers
• License

Usage

glab <command> <subcommand> [flags]

Demo

Documentation

Read the documentation for usage instructions.

Installation

Download a binary suitable for your OS at the releases page.

Quick Install

Supported Platforms: Linux and macOS

Homebrew

brew install glab

Updating (Homebrew):

brew upgrade glab

Alternatively, you can install glab by shell script:

curl -sL https://j.mp/glab-cli | sudo sh

or

curl -s https://raw.githubusercontent.com/profclems/glab/trunk/scripts/install.sh | sudo sh

Installs into usr/bin

NOTE: Please take care when running scripts in this fashion. Consider peeking at the install script itself and verify that it works as intended.

Windows

Available for download via WinGet, scoop, or downloadable EXE installer file.

WinGet

winget install glab.glab

Updating (WinGet):

winget install glab.glab

Scoop

scoop install glab

Updating (Scoop):

scoop update glab

EXE Installer

EXE installers are available for download on the releases page.

Linux

Prebuilt binaries available at the releases page.

Linuxbrew (Homebrew)

brew install glab

Updating (Homebrew):

brew upgrade glab

Snapcraft

Make sure you have snap installed on your Linux distribution.

1. sudo snap install --edge glab
2. sudo snap connect glab:ssh-keys to grant ssh access

Arch Linux

glab is available through the community/glab package or download and install an archive from the releases page. Arch Linux also supports snap.

pacman -S glab

KISS Linux

WARNING: KISS Linux may no longer be actively maintained, so links to its web domain have been removed from this README.

glab is available on the KISS Linux Community repository as gitlab-glab. If you already have the community repository configured in your KISS_PATH, you can install glab through your terminal.

kiss b gitlab-glab && kiss i gitlab-glab

Alpine Linux

glab is available on the Alpine Community repository as glab.

Install

We use --no-cache, so running apk update before is not required.

apk add --no-cache glab

Install a pinned version from edge

To ensure that by default edge is used to get the latest updates. We need the edge repository under /etc/apk/repositories.

Afterwards you can install it with apk add --no-cache glab@edge

We use --no-cache so an apk update before is not required.

echo "@edge http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk add --no-cache glab@edge

Alpine Linux Docker-way

Use edge directly

FROM alpine:3.13
RUN apk add --no-cache glab

Fetching latest glab version from edge

FROM alpine:3.13
RUN echo "@edge http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
RUN apk add --no-cache glab@edge

Nix/NixOS

Nix/NixOS users can install from nixpkgs:

nix-env -iA nixos.glab

macOS

Homebrew

glab is available via Homebrew

brew install glab

Updating:

brew upgrade glab

MacPorts

glabis also available via MacPorts

sudo port install glab

Updating:

sudo port selfupdate && sudo port upgrade glab

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 1.13+

1. Verify that you have Go 1.13+ installed

   $ go version
   go version go1.14
   

   If go is not installed, follow instructions on the Go website.

2. Clone this repository

   git clone https://gitlab.com/gitlab-org/cli.git
   cd glab
   

   If you have $GOPATH/bin or $GOBIN in your $PATH, you can just install with make install (install glab in $GOPATH/bin) and skip steps 3 and 4.

3. Build the project

   make
   

4. Change PATH to find newly compiled glab

   export PATH=$PWD/bin:$PATH
   

5. Run glab version to confirm that it worked

Authentication

Get a GitLab access token at https://gitlab.com/-/profile/personal_access_tokens or https://gitlab.example.com/-/profile/personal_access_tokens if self-managed. The token must have the api scope.

• start interactive setup

  glab auth login
  

• authenticate against gitlab.com by reading the token from a file

  glab auth login --stdin < myaccesstoken.txt
  

• authenticate against a self-managed GitLab instance by reading from a file

  glab auth login --hostname salsa.debian.org --stdin < myaccesstoken.txt
  

• authenticate with token and hostname (Not recommended for shared environments)

  glab auth login --hostname gitlab.example.org --token xxxxx
  

Configuration

By default, glab follows the XDG Base Directory Spec: global configuration file is saved at ~/.config/glab-cli. Local configuration file is saved at .git/glab-cli in the current working git directory. Advanced workflows may override the location of the global configuration by setting the GLAB_CONFIG_DIR environment variable.

• To set configuration globally:

  glab config set --global editor vim
  

• To set configuration for current directory (must be a Git repository):

  glab config set editor vim
  

• To set configuration for a specific host:

  Use the --host flag to set configuration for a specific host. This configuration is always stored in the global configuration file with or without the global flag.

  glab config set editor vim --host gitlab.example.org
  

Usage

$ glab help
GLab is an open source GitLab CLI tool bringing GitLab to your command line

USAGE
  glab <command> <subcommand> [flags]

CORE COMMANDS
  alias:       Create, list and delete aliases
  api:         Make an authenticated request to GitLab API
  auth:        Manage glab's authentication state
  check-update: Check for latest glab releases
  ci:          Work with GitLab CI pipelines and jobs
  completion:  Generate shell completion scripts
  config:      Set and get glab settings
  help:        Help about any command
  issue:       Work with GitLab issues
  label:       Manage labels on remote
  mr:          Create, view and manage merge requests
  release:     Manage GitLab releases
  repo:        Work with GitLab repositories and projects
  ssh-key:     Manage SSH keys
  user:        Interact with user
  variable:    Manage GitLab Project and Group Variables
  version:     show glab version information

FLAGS
      --help      Show help for command
  -v, --version   show glab version information

Environment Variables

GITLAB_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 or GITLAB_HOST: specify the url of the gitlab server if self hosted (eg: https://gitlab.example.com). Default is https://gitlab.com.

GITLAB_API_HOST: specify the host where the API endpoint is found. Useful when there are separate [sub]domains or hosts for git and the API endpoint: defaults to the hostname found in the git URL

REMOTE_ALIAS or GIT_REMOTE_URL_VAR: git remote variable or alias that contains the gitlab url.
Can be set in the config with 'glab config set remote_alias origin'

VISUAL, EDITOR (in order of precedence): the editor tool to use for authoring text.
Can be set in the config with 'glab config set editor vim'

BROWSER: the web browser to use for opening links.
Can be set in the config with 'glab config set browser mybrowser'

GLAMOUR_STYLE: environment variable to set your desired markdown renderer style
Available options are (dark|light|notty) or set a custom style
https://github.com/charmbracelet/glamour#styles

NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.

FORCE_HYPERLINKS: set to 1 to force hyperlinks to be output, even when not outputing to a TTY

What about Lab?

Both glab and lab are open-source tools with the same goal of bringing GitLab to your command line and simplifying the developer workflow. In many ways lab is to hub, while glab is to gh.

If you want a tool that'’'s more opinionated and intended to help simplify your GitLab workflows from the command line, then glab is for you. However, If you're looking for a tool like hub that feels like using Git and allows you to interact with GitLab, you might consider using lab.

Some glab commands such as ci view and ci trace were adopted from lab.

Issues

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

Contributing

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