## Overview During the audit for the CLI documentation style guide (https://gitlab.com/gitlab-org/gitlab/-/work_items/596327), a set of concrete inconsistencies was identified across the generated CLI documentation (produced via `make gen-docs` in [`gitlab-org/cli`](https://gitlab.com/gitlab-org/cli)). This issue tracks the remediation work. Each item below corresponds to a specific, actionable fix in the Go source files or the doc generator — not in the style guide itself. ## Inconsistencies to fix ### Structure - **Missing Synopsis section** on commands where usage nuances exist but are undocumented. Add Synopsis blocks to explain constraints, input formats, or non-obvious behavior. - **Missing or thin Examples section**: Add meaningful examples. - Optional. Every generated page has a blank line between the frontmatter and the short description, rendering as an empty paragraph in the published docs. Fix in the generator. - **Inconsistent positional argument notation**: For example, `mr/view` uses `{<id> | <branch>}` (curly braces for required); `mr/checkout` uses `[<id> | <branch> | <url>]` (square brackets); `mr/note/list` uses `[<id> | <branch>]`. Standardize on a single convention across all commands. ### Style - **Output flag naming**: Three different conventions are in use: - `-F, --output string` — `mr/list`, `mr/view`, `mr/note/list` - `-O, --output string` + `-F, --output-format string` — `issue/list` only - No output flag — `mr/create`, `mr/checkout`, `ci/trace`, `stack/*` Standardize on `-F, --output string` (the `mr` family convention) wherever an output flag is appropriate. - **Flag description punctuation**: Some descriptions end with a period, some do not. Some use angle-bracket placeholders (`<username>`), others use plain prose. End all descriptions with a period; use angle-bracket placeholders for user-supplied values. - **Boolean flag defaults**: Some boolean flags document their default explicitly (e.g. `(default false)` on `--confidential` and `--no-editor` in `issue/create`); others do not (e.g. `--draft` in `mr/create`). Always document the default for boolean flags. ### Experimental feature messaging - **Flag-level experimental annotation**: For example, `--recover` (`mr/create`, `issue/create`) and `--publish-to-catalog` (`release/create`) are annotated `(EXPERIMENTAL)` in the flag description only. Unlike command-level experiments (`stack/*`, `mr/note/list`), they do not include the three-part Synopsis boilerplate. Decide and implement a consistent approach. Either add the boilerplate to the Synopsis when any flag is experimental, or document the distinction explicitly. - **Feature flag requirements**: The `--publish-to-catalog` example in `release/create` documents a feature flag requirement in a comment block inside the Examples section. If this pattern is needed elsewhere, define and apply a standard location (Synopsis note vs Examples comment). ### User-facing gaps - **No environment variables reference**: `auth/login` references `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, `OAUTH_TOKEN`, `CI_JOB_TOKEN`, and `BROWSER` in prose. No dedicated reference page exists. Create one, or add a consolidated list to the CLI overview page. - **No cross-references between related commands**: `mr/view --comments` and `mr/note/list` share output format but neither references the other. `ci/view` and `ci/trace` are complementary but not linked. Add `Related topics` sections where commands are closely related. ## Related - Style guide issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/596327 - Audit comment: https://gitlab.com/gitlab-org/gitlab/-/work_items/596327#note_3239842655 - Experimental string cleanup precedent: https://gitlab.com/gitlab-org/cli/-/work_items/7599 - `glab mr note --help` drift bug: https://gitlab.com/gitlab-org/cli/-/work_items/8249