gitlab-cli

glab - GitLab CLI

Work seamlessly with GitLab from the command line.

glab is a CLI tool for GitLab, written in Go. It follows the same interface patterns as the GitHub CLI (gh), providing a familiar experience for managing merge requests, issues, pipelines, repositories, and more.

Documentation: philipkram.github.io/Gitlab-CLI

Installation

Homebrew (macOS & Linux)

brew tap PhilipKram/tap https://github.com/PhilipKram/Gitlab-CLI
brew install PhilipKram/tap/glab

Binary releases

Download pre-built binaries for Linux, macOS, and Windows (amd64/arm64) from the releases page.

Go install

go install github.com/PhilipKram/gitlab-cli@latest

Build from source

git clone https://github.com/PhilipKram/Gitlab-CLI.git
cd Gitlab-CLI
make build
# Binary available at ./bin/glab

Authentication

OAuth login (default)

glab authenticates via OAuth by default. Just run glab auth login and it opens your browser — no flags needed.

First run — prompts for host, protocol, and OAuth application ID, then stores everything:

$ glab auth login
? What GitLab instance do you want to log into?
  [1] gitlab.com
  [2] GitLab Self-managed
  Choice: 1
? What is your preferred protocol for Git operations on this host?
  [1] HTTPS
  [2] SSH
  Choice: 1
? OAuth Application ID: <your-app-id>

! Opening gitlab.com in your browser...
- Waiting for authentication...
✓ Logged in to gitlab.com as username

Subsequent runs — all settings are remembered, goes straight to the browser:

$ glab auth login
! Opening gitlab.com in your browser...
- Waiting for authentication...
✓ Logged in to gitlab.com as username

OAuth setup

Before using OAuth, create an OAuth application in your GitLab instance under Settings > Applications with:

• Redirect URI: http://localhost:7171/auth/redirect
• Scopes: api, read_user, write_repository, openid, profile

The CLI starts a local server on port 7171, opens your browser for authorization, and automatically exchanges the code for a token using PKCE — no client secret needed.

Token-based login

If you prefer personal access tokens over OAuth, use --token or --stdin:

# Login with a personal access token
glab auth login --token glpat-xxxxxxxxxxxxxxxxxxxx

# Login to a self-hosted GitLab instance
glab auth login --hostname gitlab.example.com --token glpat-xxxx

# Pipe a token from a file or secret manager
glab auth login --stdin < token.txt

# Check authentication status
glab auth status

# Environment variable authentication
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Required token scopes: api, read_user, write_repository

Auth login flags

Per-host configuration

Store OAuth settings per host so you don't need to pass them every time:

# Store OAuth client ID for a self-hosted instance
glab config set client_id <app-id> --host gitlab.example.com

# Store custom redirect URI (default: http://localhost:7171/auth/redirect)
glab config set redirect_uri http://localhost:8080/callback --host gitlab.example.com

# Store custom OAuth scopes
glab config set oauth_scopes "api read_user write_repository" --host gitlab.example.com

These values are also automatically saved during your first interactive glab auth login.

Token auto-refresh

OAuth tokens expire after ~2 hours. glab automatically detects when a token is expired (or about to expire within 5 minutes) and refreshes it in the background using the stored refresh token — no manual re-authentication needed.

Run glab auth status to see when your token expires:

$ glab auth status
gitlab.com
  ✓ Logged in to gitlab.com as username
  ✓ Token: gho_****
  ✓ Auth method: oauth
  ✓ Token expires: 2026-03-01 14:30:00 (in 1h45m)

If a token has already expired, glab auth status will note that it will auto-refresh on the next API call. Tokens provided via environment variables (GITLAB_TOKEN / GLAB_TOKEN) are never auto-refreshed.

Global Flags

The --repo flag lets you target any project without being in its git repository:

glab issue list -R gitlab.example.com/owner/repo
glab mr list --state opened -R gitlab.example.com/group/project

When no --repo is specified, glab resolves the host from the git remote. If the remote isn't a GitLab host, it falls back to the default host, then to the first authenticated host.

Commands

Core Commands

CI/CD Commands

Additional Commands

Utility Commands

Usage Examples

Merge Requests

glab mr create --title "Add feature" --description "Details" --draft
glab mr list --state opened
glab mr view 123
glab mr merge 123 --squash
glab mr approve 123
glab mr checkout 123
glab mr diff 123
glab mr comment 123 --body "Looks good!"
glab mr comment 123 --body "Consider refactoring this" --file "cmd/mr.go" --line 42
glab mr comment 123 --body "Good removal" --file "cmd/mr.go" --old-line 10

Issues

glab issue create --title "Bug report" --label bug --assignee @user1
glab issue list --state opened --author johndoe
glab issue view 42
glab issue close 42
glab issue comment 42 --body "Fixed in !123"

Pipelines

glab pipeline list
glab pipeline run --ref main
glab pipeline view 12345
glab pipeline jobs 12345
glab pipeline cancel 12345

Repositories

glab repo clone owner/repo
glab repo create my-project --public --init
glab repo fork owner/repo --clone
glab repo view
glab repo list --owner my-group

Upgrading

# Check for a newer version
glab upgrade --check

# Upgrade to the latest version
glab upgrade

# Skip the confirmation prompt
glab upgrade --yes

When installed via a binary release, glab upgrade downloads the latest release, verifies its checksum, and replaces the binary in-place. If glab was installed via Homebrew or a system package, the command will print the appropriate package manager instruction instead.

A startup banner also notifies you when a new version is available:

A new version of glab is available: v0.0.11 → v0.0.12
Run `glab upgrade` to update, or download from:
https://github.com/PhilipKram/Gitlab-CLI/releases/tag/v0.0.12

The version check runs in the background and caches its result locally, so it never slows down your commands.

Configuration

glab config set protocol ssh
glab config set editor vim
glab config list

# Per-host config
glab config set client_id <app-id> --host gitlab.example.com
glab config get client_id --host gitlab.example.com

Direct API Access

glab api projects
glab api users --method GET
glab api projects/:id/issues --method POST --body '{"title":"Bug"}'

# Target a specific host
glab api '/projects?membership=true' --hostname gitlab.example.com

Configuration

Configuration is stored in ~/.config/glab/. Override with GLAB_CONFIG_DIR.

Global keys

Per-host keys (use with --host)

Environment Variables

Releasing

Releases are automated via GoReleaser and GitHub Actions.

To create a release:

git tag v0.1.0
git push origin v0.1.0

This will:

1. Run tests
2. Build cross-platform binaries (linux/darwin/windows, amd64/arm64)
3. Create a GitHub Release with archives and checksums
4. Update the Homebrew formula in the homebrew-tap repo
5. Publish deb/rpm packages

Shell Completions

# Bash
source <(glab completion bash)

# Zsh
glab completion zsh > "${fpath[1]}/_glab"

# Fish
glab completion fish | source

License

MIT