Glab CLI

GLab CLI

Use glab with host-aware defaults instead of hardcoding gitlab.com.

Workflow

Follow this order unless the user explicitly asks for a single command.

1. Let glab use the current context by default

Do not run host detection by default.

In a Git repository, prefer:

glab <command>

Only add GITLAB_HOST, --hostname, or -R when the task targets another repo or another instance, or when glab resolves the wrong context.

2. Detect the platform only when context is unclear or failing

Check git remote -v only when:

• glab resolves to the wrong instance
• auth checks fail against an unexpected host
• the repository has both GitHub and GitLab remotes
• multiple GitLab hosts are present
• the task targets a different instance than the current directory

Rules:

• Prefer a GitLab remote over any GitHub or Bitbucket remote.
• If the remote host is gitlab.com, treat the platform as gitlab.com.
• If the remote host is anything else, treat the platform as self-managed-or-dedicated.
• If multiple GitLab hosts appear in git remote -v, treat the result as ambiguous and confirm before any write operation.
• If GITLAB_HOST is already set, let it override the remote-derived host.

If git remote -v does not show a GitLab remote:

• check whether the user is in the intended repository
• ask for the GitLab host or repository URL only if the task is otherwise blocked
• avoid guessing gitlab.com for a private installation

If multiple GitLab hosts are present in git remote -v, do not silently pick one for write operations. Confirm the target or set GITLAB_HOST explicitly first.

3. Reuse explicit context only when needed

For repository-scoped commands, prefer one of these patterns:

glab <command>
GITLAB_HOST="$host" glab <command>
glab <command> -R "$repo"
GITLAB_HOST="$host" glab <command> -R "$repo"

Decision rules:

• If the current directory is already the target GitLab repository, keep using bare glab commands.
• If the command targets another repository on the same instance, add -R "$repo".
• If the command targets another GitLab instance, set GITLAB_HOST="$host" and add -R "$repo" when the command is repository-scoped.
• For glab api, prefer --hostname "$host" when calling an instance other than the current repository context.

4. Confirm authentication after glab context is chosen

Check auth:

glab auth status
glab auth status --hostname "$host"
glab auth status --all

Sign in:

glab auth login
glab auth login --hostname "$host"
glab auth login --stdin < token.txt
glab auth login --hostname "$host" --token "$TOKEN"

Notes:

• glab auth login in an interactive Git repository can detect GitLab instances from Git remotes.
• GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, and OAUTH_TOKEN override stored credentials.
• Prefer --hostname for self-managed or dedicated instances instead of relying on defaults.

5. Run the task-specific command

Use these command families.

Repository and project operations

glab repo view
glab repo view "$repo"
glab repo clone "$repo"
GITLAB_HOST="$host" glab repo clone "$repo"

Merge requests

glab mr create --fill --yes
glab mr create -t "title" -d "description" -b main -s feature-branch
glab mr list
glab mr view 123
glab mr diff 123
glab mr checkout 123
glab mr note 123 -m "Looks good to me"
glab mr update 123 --label needs-review --reviewer alice
glab mr merge 123

Issues

glab issue list
glab issue view 123
glab issue create -t "title" -d "description"
glab issue create -t "title" -l bug -a alice --web
glab issue note 123 -m "Can you share repro steps?"
glab issue update 123 --label triage --assignee alice

CI/CD

glab ci list
glab ci status
glab ci view
glab ci trace 12345
glab ci run

Releases

glab release create v1.2.3 --notes "release notes"
glab release create v1.2.3 --notes-file CHANGELOG.md
glab release view v1.2.3

API

glab api projects/:fullpath
glab api projects/:fullpath/merge_requests --paginate
glab api graphql -f query='query { currentUser { username } }'
glab api --hostname "$host" projects/:fullpath

For checked command syntax and doc links, read references/verified-commands.md.

Patterns

Prefer repository context over manual URL building

Many glab commands accept -R/--repo with:

• OWNER/REPO
• GROUP/NAMESPACE/REPO
• a full HTTPS URL
• a Git URL

Use the repository path form when you already have repo from the detection step. It is shorter and easier to compose.

Prefer GITLAB_HOST for cross-instance adaptation

For most CLI commands, GITLAB_HOST="$host" is the simplest host override.

Example:

GITLAB_HOST="$host" glab repo clone "$repo"
GITLAB_HOST="$host" glab issue list -R "$repo"

For glab api, --hostname "$host" is usually clearer than relying only on environment.

Use placeholders in glab api

When running glab api inside a GitLab repository, placeholders such as :fullpath, :branch, :namespace, and :repo resolve from the current repository.

Prefer them when they remove brittle manual encoding:

glab api projects/:fullpath
glab api projects/:fullpath/repository/branches/:branch

Escalate only when platform evidence conflicts

Stop and reassess if:

• Git remotes point to both GitHub and GitLab and the intended target is unclear
• the detected host and the authenticated host disagree
• the repository lives on a private host but the task uses gitlab.com URLs
• the command mixes one instance's host with another instance's repo path