GitLab CLI (glab)
glab is pre-configured and available in your environment. Use it for all GitLab operations. Run glab <command> --help for detailed flag information.
Quick reference
# Issues
glab issue view <iid>
glab issue list --label "bug,priority::1"
glab issue create --title "title" --description-file /tmp/desc.md
glab issue note <iid> -m "comment text"
# Merge requests
glab mr create --push --title "fix: title" --description-file /tmp/desc.md
glab mr view <iid>
glab mr list --assignee <user>
glab mr update <iid> --description-file /tmp/desc.md
glab mr note create <iid> -m "comment text"
# CI/CD
glab ci status
glab ci status --output json
glab ci list
glab ci get --merge-request <iid> --with-job-details
glab ci get --pipeline-id <id> --output json
glab ci retry <job-id>
glab api projects/:id/jobs/<job-id>/trace
# Machine-readable output
glab mr list --output json | jq '.[].title'Templates: Check .gitlab/merge_request_templates/ and .gitlab/issue_templates/ for project-specific templates.
References: Always use full URLs in note/comment bodies (e.g. https://gitlab.com/org/project/-/issues/123) instead of short references (#123, !456). This applies to issues, merge requests, epics, and so on. Short refs resolve against project context and render as literal text on group-level items (epics, group work items); full URLs expand everywhere.
Comments and discussions
Use the mr note subcommands (create, resolve, reopen); flags on the root glab mr note command are deprecated.
Short, inline bodies — pass -m
glab issue note <iid> -m "comment text"
glab mr note create <iid> -m "comment text"
glab incident note <iid> -m "comment text"
# Cross-project
glab mr note create <iid> -m "..." --repo group/projectLong or Markdown bodies — pipe to stdin
glab mr note create, glab mr note update, glab mr note draft create, glab mr note draft update, glab issue note, and glab incident note read the body from stdin when -m is omitted and the input is a pipe. This avoids shell-quoting pitfalls (backticks, $, backslashes, apostrophes) and is the safest pattern for non-interactive use. A piped body also works with --attach <file>: the attachment links are added after the body.
# From a file
glab mr note create <iid> < /tmp/body.md
# Inline literal multi-line body — quoted heredoc, no shell expansion inside
glab mr note create <iid> << 'EOF'
Your **markdown** comment.
Code blocks and `inline code`, $variables, and \backslashes are all literal.
EOF
glab issue note <iid> << 'EOF'
It's the same for issues and incidents.
EOF
# Body from a file, with a screenshot attached after it
glab mr note create <iid> --attach ./screenshot.png < /tmp/body.mdFor descriptions on glab issue create / glab issue update / glab mr create / glab mr update / glab work-items create / glab work-items update, pass --description-file. A path of - reads from stdin, so a quoted heredoc works directly:
glab mr create --push --title "fix: title" --description-file - << 'EOF'
## What does this MR do?
It's a fix for `foo`.
EOF
glab mr update <iid> --description-file /tmp/desc.mdDo not nest a heredoc inside command substitution, such as --description "$(cat << 'EOF' ... EOF)" or -m "$(cat << 'EOF' ... EOF)". The default /bin/bash on macOS is bash 3.2, which fails with unexpected EOF while looking for matching '' when the body contains an apostrophe. Feed the heredoc to --description-file - or to stdin instead.
Threaded replies on merge requests
glab mr note create supports --reply <discussion-id> for replying inside an MR thread. The value can be the full discussion ID or a unique prefix of at least 8 characters.
Diff comments accept a single line (--line 42), a range (--line 10:15), a removed line (--old-line 7), or no line for a file-level comment.
glab mr note create <iid> --reply <discussion-id> -m "I agree!"
glab mr note create <iid> --file main.go --line 42 -m "Needs refactoring"
glab mr note create <iid> --file main.go --line 10:15 -m "Extract this block"
glab mr note create <iid> --file main.go --old-line 7 -m "Why was this removed?"
glab mr note create <iid> --file main.go -m "General comment on this file"
glab mr note create <iid> -m "LGTM" --unique # idempotent: skip if same body existsglab mr note resolve / reopen take the MR identifier followed by the discussion identifier. The identifier can be a discussion ID (full 40-char hex or 8+ char prefix) or a note ID (integer; the parent discussion is looked up automatically):
glab mr note resolve <iid> <discussion-id>
glab mr note resolve <iid> <note-id> # integer note ID also works
glab mr note reopen <iid> <discussion-id>Threaded replies on issues, incidents, and work items
The CLI does not wrap threaded replies for these, so you fall back to glab api. For any non-trivial body, write it to a file and post the file rather than inlining rich Markdown — inlined backticks, $, newlines, and a leading @ all break (see Content-type guidance):
# Discover the discussion ID
glab api projects/:id/issues/<iid>/discussions \
| jq '.[] | {id, body: .notes[0].body}'
# Build the body in a file, then post it with -F body=@file
cat > /tmp/reply.md << 'EOF'
@user — here's the result, with `code`, a $variable, and an emoji ✅.
EOF
glab api projects/:id/issues/<iid>/discussions/<discussion-id>/notes \
-F body=@/tmp/reply.mdFor a short, plain reply you can still inline it with -f body="reply text".
API calls
glab api auto-prepends /api/v4/. Use relative paths:
glab api user # NOT /api/v4/user
glab api projects/:id/merge_requests
glab api projects/:id/issues | jq '.[0]'Placeholders
glab api expands these built-in tokens in a path, a field value, or inline JSON:
:branch :fullpath :group :id :namespace :repo :user :username
:user and :username work anywhere. The rest are read from the current repository, so they need a Git checkout with a GitLab remote. Outside one, or to target a different project, supply the value instead:
glab api projects/:id/issues # inside a checkout
glab api projects/:id/issues -R group/project # any project; placeholder still expands
glab api projects/group%2Fproject/issues # literal path -- %2F is required
glab api projects/1234/issues # numeric project IDTo insert any other value, define your own placeholder with --placeholder <name>=<value>. In the path, glab encodes the value as a single segment, so you don't need to write %2F by hand. In -F values it is sent unchanged. For a query string value, pass it as a field with -X GET -F rather than in the path:
glab api projects/:fullpath/repository/branches/:target --placeholder target=feature/login
glab api projects/:id/issues -X GET -F search=:term --placeholder term='a&b'Anything else beginning with a colon is not a placeholder. glab sends it to the API verbatim, so the request fails at the server rather than in glab.
Content-type guidance
When using -f for PUT/POST, pass simple key=value pairs. Array bracket syntax like ids[]=1 is not supported:
# -f / --raw-field — literal string value
glab api projects/:id/merge_requests/42 -X PUT -f "assignee_id=1"
glab api projects/:id/issues/42/notes -f body="comment text"
# -F / --field — reads @file as a string. The leading @ means "read this
# file", so only pass a real path here. A literal body that starts with @
# (e.g. "@user thanks") must NOT go through -F — it would be read as a
# filename. Use -f for literal inline text, or write the body to a file and
# point -F at the file (recommended for rich/markdown bodies).
glab api projects/:id/issues/42/notes -F body=@/tmp/comment.md
# --input — raw request body from a file (or '-' for stdin). Does NOT set
# Content-Type. Without the header, JSON endpoints return HTTP 415.
glab api projects/:id/issues/42/notes \
--input /tmp/body.json \
-H "Content-Type: application/json"
# --form — multipart/form-data. Required for endpoints that take a real file
# upload, such as project or group uploads and wiki attachments. -F does not
# do this: it reads the file into a text field, and the endpoint rejects the
# request with HTTP 400.
#
# IMPORTANT: --form is mutually exclusive with -f, -F, and --input. Every
# field in a multipart request must use --form
glab api projects/:id/uploads --method POST --form "file=@screenshot.png"
# Wiki attachment — both fields must use --form
glab api projects/:fullpath/wikis/attachments --method POST \
--form "file=@screenshot.png" --form "branch=main"Arrays and nested objects
-F / --field parses a value that starts with [ or { as JSON, so arrays and nested objects go inline without a file. Placeholders are expanded inside the JSON. Invalid JSON returns an error rather than being sent as a string.
# Array of strings
glab api -X PUT projects/:id -F 'topics=["my-topic","GitLab"]'
# Nested object, with a placeholder expanded inside it
glab api projects/:id/merge_requests/42/discussions -X POST \
-F body="looks good" \
-F 'position={"position_type":"text","new_path":"main.go","new_line":42}'
# Empty array clears a field
glab api -X PUT projects/:id -F 'topics=[]'-f / --raw-field never parses JSON: a bracketed value like -f 'scopes=[api,read_api]' is sent as the literal string. Use -F with real JSON for arrays. On GET and DELETE requests, and whenever --input is used, -F arrays are serialized as repeated key[]= query parameters.
Common mistakes
-mor piped stdin is required onnotecommands — with neither,glab mr note create,glab issue note, andglab incident noteopen$EDITORon a TTY, which hangs in non-interactive environments.- Use
glab mr note create, notglab mr note -m— the--message,--unique,--resolve, and--unresolveflags on the rootglab mr notecommand are deprecated. Use thecreate,resolve, andreopensubcommands instead. - Editor-opening flags are unsafe in agent environments — avoid
--description "-"onissue create/mr create/mr updateand avoid omitting-monnotecommands. Pass an explicit value or pipe from stdin instead. glab issue noteandglab incident noteonly post root-level comments — useglab mr note create --replyfor MRs, orglab api .../discussions/<id>/notesfor issues/incidents (write the body to a file and pass-F body=@filefor anything non-trivial).- A note with only an attachment needs
</dev/nullin scripts — when stdin is not a terminal,notecommands read it as the body and wait until it closes. Runglab mr note create <iid> --attach ./shot.png </dev/nullso glab neither waits on an open pipe nor consumes a loop's input. --attach -uses stdin for the file — the body must then come from-m, for examplepngpaste - | glab mr note create <iid> -m "Repro" --attach -.-Fdoes not upload files —-F file=@x.pngsends the file contents as a string field, and upload endpoints reject it with HTTP 400. Use--form file=@x.pngfor multipart uploads.-Freads a file only to fill a text field, such as a note body. Also,--formis mutually exclusive with-f,-F, and--input— every field in a multipart request must use--form(e.g.--form "file=@x.png" --form "branch=main").--inputrequires an explicitContent-Typeheader —glab api --input file.jsonsends raw bytes without setting Content-Type, causing HTTP 415. Add-H "Content-Type: application/json"or use-f/-Finstead.glab ci retrytakes a job ID, not a pipeline ID — to retry an entire pipeline, useglab api projects/:id/pipelines/<id>/retry -X POST.glab ci tracestreams — it blocks until the job finishes. For agents, useglab ci getfor pipeline state orglab api projects/:id/jobs/<job-id>/traceto fetch a finished log.glab ci viewis interactive — terminal UI that blocks. Useglab ci statusorglab ci getfor pipeline state instead.- Always
--pushonglab mr create— without it the remote branch may not exist and MR creation fails. - No
--stateonmr list— use--all,--merged, or--closed. - No
--bodyflag —--bodyis aghflag.glabuses--description. - Labels —
--labelto add,--unlabelto remove. Scoped labels likestatus::doingauto-replace within their scope.
Contributing improvements
This skill ships inside glab. Its front matter records where it is maintained: metadata.source-project and metadata.source-path.
If any guidance here is inaccurate or outdated, such as a command that no longer works, a wrong flag, or incorrect API behavior:
- Use
glab apito read the file<source-path>/SKILL.mdinsource-projectonmain. If the issue is already fixed there, use that guidance instead of opening another merge request. - After a release with the fix, upgrade
glab. Refresh your copy:glab skills get glab: the upgraded binary already has it.- Installed with
glab skills install(project or user): a copy is glab-installed only if its front matter hassource-projectset togitlab-org/cli. If everyglab/in both locations is glab-installed, runglab skills update glabfrom the project. It replaces all of them. Otherwise, refresh only the glab-installed ones withglab skills install glab --forcefrom that project (add--globalfor the user location). Ask the user about any copy withoutsource-project. - Installed with
--path: runglab skills install glab --path <parent-dir> --force. - Third-party copy: refresh it at its source.
- If the problem is still present on
main, confirm with the user, then open a merge request againstsource-projectwith the fix. Keep changes focused: one fix per merge request, with a Conventional Commits message.