GitLab CLI (glab)

GitLab CLI for merge requests, pipelines, issues, and API access.

Installation

Install on Arch

sudo pacman -S glab

Verify package info

pacman -Si glab | grep -E "^(Name|Version|Repository)"

Authentication

Check auth status (run this first)

glab auth status

If you see 401 Unauthorized — your token is expired. See Token Renewal below.

Interactive login

glab auth login --hostname gitlab.com

Select Token, paste your PAT.

Non-interactive login (scripted)

glab auth login --hostname gitlab.com --token "$(yq -r '.hosts["gitlab.com"].token' ~/atelier/_vaults/mounted/credentials/glab/config.yml)"

glab auth login --hostname gitlab.com --token glpat-xxxxxxxxxxxx

Token Renewal

When glab auth status returns 401 Unauthorized, the PAT has expired.

Step 1: Generate a new token

GitLab → Settings → Access Tokens → Add new token
Name: glab-cli-2026
Scopes: api, write_repository, read_repository
Expiration: set to 1 year or as policy allows

Step 2: Update the credential file

# Edit the config — the token lives under hosts.gitlab.com
vim ~/atelier/_vaults/mounted/credentials/glab/config.yml

The token line MUST be token: glpat-xxxxx — NOT token: !!null glpat-xxxxx. The !!null YAML tag forces the value to null and yq/glab will ignore the actual token string. If you see !!null, remove it.

Correct

hosts:
    gitlab.com:
        token: glpat-your-actual-token-here

Broken (!!null overrides the value)

hosts:
    gitlab.com:
        token: !!null glpat-your-actual-token-here

Step 3: Verify the token is readable

yq -r '.hosts["gitlab.com"].token' ~/atelier/_vaults/mounted/credentials/glab/config.yml

Should return glpat-xxxxx. If it returns null, the !!null tag is still there.

Step 4: Login with the new token

glab auth login --hostname gitlab.com --token "$(yq -r '.hosts["gitlab.com"].token' ~/atelier/_vaults/mounted/credentials/glab/config.yml)"

Step 5: Verify

glab auth status

Should show ✓ Logged in to gitlab.com.

Step 6: Re-encrypt the credential file (if using age/gopass)

# If credentials are age-encrypted, re-encrypt after editing
age -e -R ~/.age/recipients/self.txt -o config.yml.age config.yml

yq Patterns for Credential Files

Inspect YAML keys without revealing values

yq 'keys' ~/atelier/_vaults/mounted/credentials/glab/config.yml

Inspect nested keys

yq '.hosts | keys' ~/atelier/_vaults/mounted/credentials/glab/config.yml

Inspect fields under a host (keys only, no values)

yq '.hosts["gitlab.com"] | keys' ~/atelier/_vaults/mounted/credentials/glab/config.yml

Extract a safe field to test yq path syntax

yq -r '.git_protocol' ~/atelier/_vaults/mounted/credentials/glab/config.yml

This should return ssh. If it works, your yq path syntax is correct and you can trust it for the token field.

Keys with dots (common gotcha)

# WRONG — yq interprets dots as nested keys
yq '.hosts.gitlab.com.token'

# CORRECT — bracket notation for keys with dots
yq '.hosts["gitlab.com"].token'

Repository Management

Create a new project on GitLab

glab repo create domus-api --private

Clone a GitLab repo

glab repo clone EvanusModestus/domus-api

View repo info

glab repo view

List your projects

glab repo list

Merge Requests (GitLab’s PRs)

Create a merge request

glab mr create --title "feat: association graph endpoints" --description "Adds /associations API"

List open MRs

glab mr list

View MR details

glab mr view 42

Approve an MR

glab mr approve 42

Merge an MR

glab mr merge 42 --squash --remove-source-branch

Check MR CI pipeline status

glab ci status

Issues

Create an issue

glab issue create --title "Add YAML persistence" --label "enhancement"

List issues

glab issue list

Close an issue

glab issue close 15

CI/CD Pipelines

View pipeline status for current branch

glab ci status

List recent pipelines

glab ci list

Trigger a pipeline manually

glab ci run

View CI job logs

glab ci trace <job-id>

GitLab API — Direct Access

Like gh api, glab api gives raw REST access.

Get project details

glab api projects/EvanusModestus%2Fdomus-api | jq '{name: .name, visibility: .visibility}'

GitLab API uses %2F for / in project paths (URL encoding).

Get latest pipeline status

glab api projects/EvanusModestus%2Fdomus-api/pipelines | jq '.[0] | {id, status, ref}'

List project variables (CI/CD secrets)

glab api projects/EvanusModestus%2Fdomus-api/variables | jq '[.[] | {key, protected, masked}]'

Snippets (GitLab’s Gists)

Create a snippet

glab snippet create validate.sh --title "domus-api validation script" --visibility private

List snippets

glab snippet list

gh vs glab — Side by Side

Action GitHub (gh) GitLab (glab)

Action	GitHub (`gh`)	GitLab (`glab`)
Auth	`gh auth login`	`glab auth login`
Create repo	`gh repo create NAME --private`	`glab repo create NAME --private`
Create PR/MR	`gh pr create`	`glab mr create`
List PRs/MRs	`gh pr list`	`glab mr list`
CI status	`gh run list`	`glab ci status`
API access	`gh api repos/OWNER/REPO`	`glab api projects/OWNER%2FREPO`
Create issue	`gh issue create`	`glab issue create`
Snippets/Gists	`gh gist create`	`glab snippet create`

Auth

gh auth login

glab auth login

Create repo

gh repo create NAME --private

glab repo create NAME --private

Create PR/MR

gh pr create

glab mr create

List PRs/MRs

gh pr list

glab mr list

CI status

gh run list

glab ci status

API access

gh api repos/OWNER/REPO

glab api projects/OWNER%2FREPO

Create issue

gh issue create

glab issue create

Snippets/Gists

gh gist create

glab snippet create