GLab: Install and Use the GitLab CLI

To work with a GitLab project from a terminal, you need a way to connect commands to GitLab. glab is GitLab’s command-line client for signing in and managing project work from the terminal.

I’ll show you how to install glab and sign in, then use its project commands to view issues or merge requests.

TL;DR

GLab, commonly invoked as glab, lets you authenticate with GitLab and manage project work from the terminal.

• Install from a supported package source such as Homebrew or use the official releases page for your platform.
• Run glab auth login and choose the right GitLab host.
• Use commands such as glab issue list or glab mr list inside a repository.

What Is the GitLab CLI (glab)?

GLab is GitLab’s open-source command-line client. Its command groups include glab issue, glab mr, glab ci and glab auth.

The command is named glab, and the client supports GitLab.com, GitLab Dedicated and GitLab Self-Managed. Run glab --help to see command groups and glab --version to identify the installed build.

For Git repository setup, see our guide to installing Git on Linux.

How to Install and Use glab Step by Step

Install the CLI and authenticate against the GitLab instance that hosts your project. Then run a read-only command to confirm the repository context before changing anything.

Step 1: Choose an installation source

GitLab’s current project identifies Homebrew as an officially supported package manager across macOS, Linux, and Windows through WSL. On a system with Homebrew, use:

brew install glab

For other platforms, follow the installation guidance linked from the official GitLab CLI documentation or download a matching asset from the official project releases after checking the operating system and CPU architecture.

A distribution package fits a workflow where system updates manage developer tools, but community builds can lag behind the project releases. Check the package catalog and release date, or choose a release binary after confirming its platform and CPU architecture.

Step 2: Authenticate with GitLab

Run the interactive login command from your terminal. Choose the host that serves the project you intend to use.

glab auth login

For GitLab.com, choose OAuth through a browser or device authorization in a headless terminal. A personal access token also works when required by your workflow. Check GitLab’s authentication documentation for its scopes.

GLab uses the operating system keyring when available. Without one, it may save credentials as plaintext in its configuration file. Do not commit that file or paste its contents into logs.

Step 3: Check the selected host

After login, inspect the account and host before using a command that changes project data. This status check is a safer first test than creating an issue or merge request.

glab auth status

For a self-managed server, provide its hostname during login when prompted or with the documented hostname option.

When a command supports -R, use it to name the intended repository explicitly.

Step 4: List issues or merge requests

Start with a list operation to confirm the project and permissions. The issue-list command reads issues, while merge-request commands use the mr family.

glab issue list
glab mr list

The list commands return project items available to the authenticated user. Results can be paginated with --page and --per-page where supported. Use glab issue --help or glab mr --help to inspect command-specific flags before changing an issue or approving a request.

Step 5: Target another project when needed

A local Git remote is convenient when it matches the project, but commands can target a different repository explicitly. The --repo option accepts a project path, full URL, or Git URL for commands that document it.

glab issue list --repo GROUP/NAMESPACE/PROJECT

Replace the placeholder with the full project path, including any nested groups. Copy it from the project URL and check the namespace before a write operation. Similar project names can point to different repositories.

Fix Common glab Authentication and Host Issues

If a command fails after login, compare the selected host and project with the target shown in the error before changing server settings.

GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, and OAUTH_TOKEN can take precedence over saved credentials. An older shell-profile or CI variable may select a different identity. Check whether a variable exists without displaying its value.

Keep secrets out of logs and bug reports.

A “none of the git remotes configured for this repository” message means glab did not identify a suitable GitLab host from the remotes. Inspect the configured remote with git remote -v, then authenticate explicitly with the intended hostname.

git remote -v
glab auth login --hostname gitlab.example.com

A 404 from a self-managed installation can involve a reverse proxy or a project path that differs from the clone URL. Verify the canonical project URL and API endpoint with the instance administrator before changing proxy configuration. Community reports describe proxy URL rewriting as one possible cause, but the server configuration must confirm it.

GitLab CI job-token access depends on endpoint and project permissions. Use documented CI auto-login for supported commands. Do not put a job token in GITLAB_TOKEN because GLab treats it as an access token.

Check endpoint permissions after an authorization error.

Use help at the group or action level to find the option supported by your installed command.

glab issue --help
glab mr --help

Pagination matters on busy projects because a list may span multiple pages. The documentation describes page and per-page options for commands that support them. Confirm the options in the installed version’s help before adding them to a script.

Before a write, confirm the repository path shown by a read-only list or view command.

Step 6: Use CI authentication deliberately

In a pipeline, use the documented CI authentication path and pass the job token only to supported endpoints. For example, keep the token in the CI environment rather than embedding it in the command or a committed file:

glab issue list

When a job fails with an authorization error, identify the failing endpoint and verify that the project or group permits the job token to use it. This is a permission check, not necessarily a glab installation problem. Keep debug output free of secret values when diagnosing the job.

Step 7: Protect saved credentials

Check the configuration file permissions without printing its contents:

stat -c '%a %n' ~/.config/glab-cli/config.yml

Restrict access to the file and exclude it from repositories and shared backups.

Token rotation should be handled at the GitLab account or instance that issued the credential. After replacing a token, check authentication status again and retry a read-only command. Avoid printing environment variables because terminal history and CI logs can persist longer than the session.

For a self-managed instance, the hostname must identify the GitLab web host rather than an unrelated clone mirror or proxy alias. If login succeeds but project calls return 404, compare the clone URL, configured host, and canonical project URL. Ask the instance administrator to confirm any custom API path before changing client settings.

Keep the first project check read-only until you have confirmed the account can see the intended repository.

When a command returns no records, check filters and pagination before assuming the project is empty. A list may be scoped to open items or a particular state, and the current command’s help explains its filters. Repeat the smallest read-only query that can distinguish a filter mismatch from an access problem.

For scripts, make the project target explicit when the process may run outside the repository directory. That prevents a working-directory change from silently changing which project receives a later write. Keep the target path in reviewed configuration rather than accepting arbitrary user input in a destructive automation step.

Before creating an issue or opening a merge request, verify the project and review the exact command options. A list command is a safer check because it reads existing records. A write command can notify collaborators or change project state, so confirm its target and payload first.

A syntactically valid command can fail when the server disables its endpoint or the account lacks the required role. Check the reported endpoint and permission before changing client settings.

For a team, document the expected host and minimum permissions beside the command in its project runbook. That gives a new contributor a way to distinguish setup steps from project policy. Keep personal tokens out of shared examples and prefer the organization’s approved authentication method.

Conclusion: Keep GitLab Work in Your Terminal

Use glab when a GitLab project task belongs in the same terminal as your Git work. Confirm authentication and project context, then check the installed help output before a change. This keeps the command aligned with the client version and the permissions on that instance.

For the official reference, use the GitLab CLI documentation and the GitLab CLI project. For related command-line workflows, see our guides to Git stash and the Linux command line.

FAQ

These answers cover common setup questions not addressed by the section headings.