Glab cli

GitLab CLI (glab)

Interact with GitLab from the command line: repositories, issues, merge requests, CI/CD pipelines, releases, and API requests across GitLab.com, GitLab Self-Managed, and GitLab Dedicated instances.

Verified with glab 1.106.0.

Version Compatibility

If the installed glab version is not 1.106.0, run glab --version and verify version-gated commands with glab <command> <subcommand> --help before using them. Notable recent changes:

• --jq on standard non-api commands requires v1.100.0+. Older versions may still support --output json; pipe to external jq or use glab api.
• glab api --form requires v1.91.0+.
• glab todo list / todo done require v1.92.0+.
• glab search semantic and issue/mr create --template require v1.93.0+.
• mr note subcommands and flags changed across recent versions. If a note/comment command or flag is missing, verify with glab mr note <subcommand> --help.
• ci get --merge-request / --status require v1.98.1+.
• glab api placeholder URL encoding for :fullpath was fixed in v1.102.0; manually URL-encode paths if older versions mis-handle nested project paths.
• glab packages and glab container-registry are recent: package/registry listing in v1.103, package upload in v1.104, package download/delete in v1.106.

Agent Guidelines

• Always use long flag names in commands (--output, --output-format, --field). Where present, the short flag -F maps to --output-format on issue list/incident list, --field on glab api, --notes-file on release create, and --output elsewhere (with variable export accepting json/export/env instead of the usual text/json).
• Default text output is most token-efficient for quick reading. For structured extraction on supported read commands, use --output json --jq '<expr>' when the command has --output; a few newer groups expose --jq without --output. glab has no gh --json FIELDS, general --csv, Go-template, or custom --format mode.
• glab api has no built-in --jq flag. Pipe API output to external jq; for large paginated arrays, prefer glab api --paginate --output ndjson | jq ....
• Use --output-format ids on issue list and incident list when only IDs are needed. For list commands with JSON output but no --output-format (for example mr list), use --output json --jq.
• Use ci status --compact for quick pass/fail checks. ci view is TUI-only and unsuitable for programmatic use.
• Use ci status --output json for machine-readable status; it is incompatible with --live and --compact.
• ci trace streams job output and can block until a running job finishes — there is no --no-follow flag. Check job status first with ci get; trace only completed jobs, redirecting output to a file.
• Use variable export --output env for compact KEY=VALUE output instead of the default JSON.
• Omit --comments, --system-logs, --with-job-details, and --with-variables unless specifically needed — they significantly increase output size.
• Scope list output with --per-page to control result count. Most list commands use --page/--per-page; commands with ranked results, such as search semantic, may use --limit.
• Use glab search semantic only for beta GitLab Duo semantic code search when approximate natural-language matching is acceptable. For exact text, regex, or multi-file code exploration, clone to a temp directory (glab repo clone owner/repo <temp-dir> -- --depth 1) and search locally with file-reading and search tools.
• Use glab api for quick reads of specific known files or repository metadata.
• When unsure about flags, run glab <command> <subcommand> --help.

Safety

• Write operations include command verbs such as create, update, merge, approve, close, delete, run, retry, cancel, trigger, note, resolve, reopen, upload, rotate, revoke, plus todo done, subscribe/unsubscribe, fork, archive, and variable/settings changes. Confirm with the user before executing.
• glab mr merge defaults --auto-merge to true — when a pipeline is running, this queues the MR to merge when checks pass. Use --auto-merge=false only when immediate merge is intended, and use --sha to guard the reviewed HEAD.
• glab api method defaults: GET without parameters, POST when --field, --raw-field, or --form are present. Use explicit --method (-X) for PUT, PATCH, and DELETE.
• Secret exposure: token create, token rotate, auth status --show-token, variable get, and variable export can expose token or secret values into agent context. List metadata first when possible; do not print secret values unless explicitly requested.
• Comment shell escaping: For note/comment bodies containing backticks, $, or shell metacharacters, pass the body via stdin where supported (for example glab mr note create 123 < body.md) or load a temp file into the flag (--message "$(<body.md)") instead of inlining it in double quotes.
• Package and registry deletion (packages delete, container-registry ... delete, release delete --with-tag) can remove published artifacts or tags. Require explicit target IDs/names before executing.

Prerequisites

Verify glab is installed and authenticated:

glab --version
glab auth status

If not authenticated: glab auth login (interactive) or glab auth login --hostname <host> --token <pat> (non-interactive). Check command-specific flags with glab <command> --help.

Host Targeting and Self-Managed GitLab

glab auto-detects the target instance from Git remotes. Override project/host context with -R OWNER/REPO (also accepts nested namespaces and URLs), GITLAB_HOST, or --hostname on auth commands.

• Host precedence: -R/--repo → Git remote → GITLAB_HOST/GITLAB_URI/GL_HOST → local config → global config → gitlab.com.
• Token precedence: GITLAB_TOKEN/GITLAB_ACCESS_TOKEN/OAUTH_TOKEN env vars override --token, keyring credentials, and config-file tokens.
• Multi-instance: Switching is implicit via context (git remote, env var, -R). There is no explicit auth switch command.

Self-managed login:

glab auth login --hostname gitlab.example.com --token <pat>

Minimum token scopes: api, write_repository. In GitLab CI, set GLAB_ENABLE_CI_AUTOLOGIN=true with GITLAB_CI=true to use CI_JOB_TOKEN and CI_SERVER_FQDN; GITLAB_TOKEN still takes precedence.

Common Flags

Available on most read commands:

• --output text|json -- Output format. Default: text on most read commands.
• --jq EXPRESSION -- Filter JSON output using jq syntax. Use with --output json when the command has --output; not available on glab api.
• --page N --per-page N -- Pagination. Default per-page varies by command.
• -R/--repo OWNER/REPO -- Target a different project. Also accepts full URLs and nested group paths.
• --web / -w -- Open the result in a browser.

Issues

Use these commands to list and view issues. For creating, updating, closing, commenting, advanced triage, subscriptions, and deletion, load Issues.

List

List issues in a project, filtered by label, assignee, or search query. Defaults to open issues.

glab issue list
glab issue list --label bug --assignee @me
glab issue list --closed --search "error" --per-page 10
glab issue list --output-format ids                       # Most compact: one IID per line
glab issue list --output json --jq '.[].iid'

Key filters: --search with --in title,description, --label/--not-label, --assignee @me/--not-assignee, --author, --milestone, --issue-type, --iteration, --closed/--all, --group + --epic.

Output: --output-format ids|urls (default details) is most compact for IDs/URLs; its short flag is -F. JSON uses --output json --jq; short output flag is -O, not -F.

View

Display an issue's title, description, labels, assignees, and status.

glab issue view 123
glab issue view 123 --comments
glab issue view 123 --output json
glab issue view 123 --output json --jq '.title'

Key flags: --comments includes comments and activities; --system-logs includes system activities; --page/--per-page paginate comments.

Merge Requests

Use these commands to view and inspect MRs. For creating, updating, merging, reviewing, and managing MRs, load Merge Requests.

List

List merge requests in a project, filtered by author, label, or search query. Defaults to open MRs.

glab mr list
glab mr list --assignee @me --merged
glab mr list --label "needs-review" --draft
glab mr list --source-branch feature-x --per-page 10
glab mr list --output json --jq '.[].iid'

Key filters: --search, --assignee @me, --reviewer, --author, --label/--not-label, --milestone, --source-branch, --target-branch, --closed/--merged/--all, --draft/--not-draft, --deployed-after/--deployed-before + --environment, --group.

Output: mr list has no --output-format; use --output json --jq for structured extraction.

View

Display an MR's title, description, reviewers, and metadata. Text output shows reviewer names but not approval or pipeline status — use --output json for those fields.

glab mr view 123
glab mr view 123 --comments
glab mr view 123 --unresolved
glab mr view 123 --output json

Key flags: --comments, --resolved/--unresolved (implies --comments), --system-logs, and --page/--per-page for comment context size.

Diff

View the file changes in an MR as a unified diff.

glab mr diff 123
glab mr diff 123 --color=never                            # Machine-readable output

Key flags: --color=never for machine-readable output; --raw for pipeable raw diff.

There is no --name-only flag. Use glab api for a changed file summary — see API Patterns.

Approvers

List approval requirements and status for an MR.

glab mr approvers 123
glab mr approvers 123 --output json --jq '.rules[] | {name, approvals_required, approved}'

Use --output json --jq to extract rule names, required approvals, or approval state.

CI/CD Pipelines

Use these commands to view pipeline and job status. For running pipelines, retrying jobs, managing schedules, and working with variables, load CI/CD.

List Pipelines

List recent pipelines, filtered by status, branch, or source.

glab ci list
glab ci list --status failed --per-page 5
glab ci list --ref main --source push
glab ci list --yaml-errors                                # Find pipelines with config errors
glab ci list --status failed --output json --jq '.[].id'

Key filters: --status (running, pending, success, failed, canceled, skipped, created, manual, waiting_for_resource, preparing, scheduled), --ref, --source (push, trigger, pipeline, parent_pipeline, merge_request_event), --name, --scope, --username, --sha, and --yaml-errors.

View Pipeline Details

View a pipeline's summary, job statuses, and variables. Specify a pipeline with --pipeline-id or --branch — positional arguments are not accepted.

glab ci get --pipeline-id 12345
glab ci get --pipeline-id 12345 --with-job-details
glab ci get --merge-request 42 --status failed --with-job-details
glab ci get --branch main --output json

Key flags: --pipeline-id, --branch, --merge-request (MR head pipeline; requires v1.98.1+), --status (job state filter; requires v1.98.1+), --with-job-details, --with-variables (requires Maintainer role and may expose values).

Pipeline Status

Show the latest pipeline status for a branch.

glab ci status
glab ci status --compact                                  # Most concise status check
glab ci status --branch main
glab ci status --branch main --output json

Key flags: --compact for the most concise check, --branch, --live for streaming updates, and --output json for machine-readable status. JSON is incompatible with --live and --compact.

Repositories

View

Display a repository's description and metadata. Use --branch to view branch-specific repository metadata.

glab repo view
glab repo view owner/repo --output json
glab repo view --branch develop
glab repo view owner/repo --output json --jq '.default_branch'

Clone

Clone a repository locally. Use a shallow clone for code exploration when exact text, regex, or multi-file reasoning is needed.

glab repo clone owner/repo [target-directory]
glab repo clone owner/repo [target-directory] -- --depth 1
glab repo clone --group my-group --archived=false --paginate

List

List repositories accessible to the authenticated user. Defaults to projects you own (--mine).

glab repo list
glab repo list --group my-group --include-subgroups
glab repo list --starred --per-page 50
glab repo list --all --output json
glab repo list --group my-group --output json --jq 'length'

Key filters: --mine (default), --all, --member, --user, --starred, --group, --include-subgroups, --archived true|false, --order, --sort.

Search and Semantic Code Search

Search for repositories by keyword, or use beta GitLab Duo semantic code search for approximate natural-language code matching. For exact text or regex, clone and search locally.

glab repo search --search "keyword" --per-page 20
glab repo search --search "cli" --output json
glab search semantic --query "authentication middleware" --repo owner/repo --limit 5
glab search semantic --query "CI pipeline triggers" --repo owner/repo --output json --jq '.[].path'

glab search semantic requires glab v1.93.0+ and GitLab Duo semantic code search. For repository creation, updating, forking, contributors, labels, milestones, todos, packages, and registry commands, load Project Management.

Releases

List

List releases in a project, ordered by creation date (newest first).

glab release list
glab release list --per-page 10
glab release list --output json --jq '.[].tag_name'

View

Display a release's notes, tag, and assets. Omit the tag to view the latest release.

glab release view v1.2.0
glab release view --output json --jq '.tag_name'

For creating, uploading, downloading, deleting releases, and generating changelogs, load Releases.

API

Use glab api for operations beyond standard subcommands. Requests are authenticated automatically.

glab api 'projects/:fullpath/issues?per_page=5'
glab api projects/:fullpath/merge_requests/123 | jq '.title'

Endpoint placeholders (:id, :fullpath, :user, :branch) are populated from the current Git context; :fullpath URL-encodes group/project paths in current glab versions. Method defaults are GET without parameters and POST when --field, --raw-field, or --form are present; use explicit --method for PUT, PATCH, and DELETE.

The -F flag means --field on glab api, not --output. glab api has no --jq flag — pipe to external jq:

glab api projects/:fullpath/issues | jq '.[].title'
glab api projects/:fullpath/issues --paginate --output ndjson | jq 'select(.state == "opened")'

For endpoint patterns, pagination, GraphQL, and common recipes, load API Patterns.

Other Commands

Run glab <command> --help for exact flags. Load Project Management for label and milestone mutations, repository settings, forking, contributors, todos, iterations, work items, packages, and registry commands.

• glab label list --output json --jq '.[].name' -- List labels. Use --group for group labels.
• glab milestone list --project my-group/my-project --state active -- List milestones; use --show-id before milestone get/edit/delete.
• glab incident list --output-format ids / glab incident view 456 -- Incidents use the issue interface, including --output-format ids|urls.
• glab todo list -- List todos (requires v1.92.0+). todo done changes GitLab state.
• glab token, glab packages, and glab container-registry expose or mutate credentials/artifacts. Package/registry listing requires v1.103.0+, package upload v1.104.0+, and package download/delete v1.106.0+.

Troubleshooting

• Not authenticated -- Run glab auth login. Verify with glab auth status.
• auth status shows wrong host -- glab auth status respects GITLAB_HOST. Use --hostname or GITLAB_HOST to check a specific instance.
• Wrong project targeted -- Use -R OWNER/REPO or verify Git remotes with git remote -v.

References

• Merge Requests -- Creating, updating, merging, reviewing, and managing MRs
• Issues -- Creating, updating, closing, commenting, triage, subscriptions, and deletion
• CI/CD -- Pipelines, jobs, schedules, and variables
• API Patterns -- glab api, pagination, GraphQL, file reads, and fallback recipes
• Project Management -- Labels, milestones, repository settings, todos, work items, packages, and registry
• Releases -- Release creation, assets, deletion, and changelog generation

Documentation

• GitLab CLI documentation -- Official glab docs
• GitLab CLI releases -- Version history and release notes
• GitLab REST API -- REST endpoint reference for glab api
• GitLab GraphQL API -- GraphQL schema and query reference