glab

# 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 ```shell # Issues glab issue view <iid> glab issue list --label "bug,priority::1" glab issue create --title "title" --description "$(cat /tmp/desc.md)" glab issue note <iid> -m "comment text" # Merge requests glab mr create --push --title "fix: title" --description "$(cat /tmp/desc.md)" glab mr view <iid> glab mr list --assignee <user> glab mr update <iid> --description "$(cat /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` ```shell 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/project ``` ### Long or Markdown bodies — pipe to stdin (preferred for MR notes) `glab mr note create` reads the body from stdin when its input is a pipe. This avoids shell-quoting pitfalls (backticks, `$`, backslashes) and is the safest pattern for non-interactive use. ```shell # 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` and `glab incident note` do **not** read stdin. For long bodies on those commands, use `glab api` with `-F body=@file` (see [Content-type guidance](#content-type-guidance)) or inline a quoted heredoc into `-m`: ```shell glab issue note <iid> -m "$(cat << 'EOF' Your **markdown** comment. Code blocks and `inline code` are safe. EOF )" ``` For descriptions on `glab issue create` / `glab mr create` / `glab mr update`, inline a quoted heredoc into `--description`, or for very large or reusable bodies write to a file and use `--description "$(cat /tmp/desc.md)"`. ### 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. ```shell 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 exists ``` `glab 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): ```shell 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](#content-type-guidance)): ```shell # 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.md ``` For 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: ```shell glab api user # NOT /api/v4/user glab api projects/:id/merge_requests glab api projects/:id/issues | jq '.[0]' ``` ### Placeholders `glab api` expands exactly these 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: ```shell 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 ID ``` 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: ```shell # -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. ```shell # 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 - **`-m` is required on `note` commands** — without it, `glab issue note` and `glab incident note` open `$EDITOR` (which hangs in non-interactive environments). `glab mr note create` falls back to reading stdin on a pipe, but still opens `$EDITOR` on a TTY. - **Use `glab mr note create`, not `glab mr note -m`** — the `--message`, `--unique`, `--resolve`, and `--unresolve` flags on the root `glab mr note` command are deprecated. Use the `create`, `resolve`, and `reopen` subcommands instead. - **Editor-opening flags are unsafe in agent environments** — avoid `--description "-"` on `issue create` / `mr create` / `mr update` and avoid omitting `-m` on `note` commands. Pass an explicit value or pipe from stdin instead. - **`glab issue note` and `glab incident note` only post root-level comments** — use `glab mr note create --reply` for MRs, or `glab api .../discussions/<id>/notes` for issues/incidents (write the body to a file and pass `-F body=@file` for anything non-trivial). - **`-F` does not upload files** — `-F file=@x.png` sends the file contents as a string field, and upload endpoints reject it with HTTP 400. Use `--form file=@x.png` for multipart uploads. `-F` reads a file only to fill a *text* field, such as a note body. Also, `--form` is 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"`). - **`--input` requires an explicit `Content-Type` header** — `glab api --input file.json` sends raw bytes without setting Content-Type, causing HTTP 415. Add `-H "Content-Type: application/json"` or use `-f` / `-F` instead. - **`glab ci retry` takes a job ID, not a pipeline ID** — to retry an entire pipeline, use `glab api projects/:id/pipelines/<id>/retry -X POST`. - **`glab ci trace` streams** — it blocks until the job finishes. For agents, use `glab ci get` for pipeline state or `glab api projects/:id/jobs/<job-id>/trace` to fetch a finished log. - **`glab ci view` is interactive** — terminal UI that blocks. Use `glab ci status` or `glab ci get` for pipeline state instead. - **Always `--push` on `glab mr create`** — without it the remote branch may not exist and MR creation fails. - **No `--state` on `mr list`** — use `--all`, `--merged`, or `--closed`. - **No `--body` flag** — `--body` is a `gh` flag. `glab` uses `--description`. - **Labels** — `--label` to add, `--unlabel` to remove. Scoped labels like `status::doing` auto-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: 1. Use `glab api` to read the file `<source-path>/SKILL.md` in `source-project` on `main`. If the issue is already fixed there, use that guidance instead of opening another merge request. 2. 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 has `source-project` set to `gitlab-org/cli`. If every `glab/` in both locations is glab-installed, run `glab skills update glab` from the project. It replaces all of them. Otherwise, refresh only the glab-installed ones with `glab skills install glab --force` from that project (add `--global` for the user location). Ask the user about any copy without `source-project`. - Installed with `--path`: run `glab skills install glab --path <parent-dir> --force`. - Third-party copy: refresh it at its source. 3. If the problem is still present on `main`, confirm with the user, then open a merge request against `source-project` with the fix. Keep changes focused: one fix per merge request, with a Conventional Commits message.