## Summary Issue [#8323](https://gitlab.com/gitlab-org/cli/-/work_items/8323) surfaced a user-facing documentation gap in `glab repo list`. The issue was closed as "expected behavior", but the discussion explicitly flagged that the CLI help text is misleading in two ways: 1. The `--all` flag description says **"List all projects on the instance."** — but it does not iterate through pages. It only removes ownership/membership filters while still returning a single page of results. 2. The `--per-page` flag has no documented upper limit, yet the GitLab REST API caps it at 100. Passing `--per-page 200` silently returns only 100 results with no warning. `@faleksic` confirmed in the thread: _"we might want to improve the documentation around the command"_. ## What needs to be checked - [x] Does the `--all` flag description in `glab repo list --help` accurately reflect what it does? — **No.** Current wording (`List all projects on the instance.`) is misleading. `--all` only suppresses the implicit `Owned=true` filter (`list.go:144`); it does not loop pages. - [x] Does the `--per-page` flag description document the API-imposed maximum of 100? — **No.** No upper bound is mentioned. The underlying go-gitlab `ListOptions.PerPage` passes straight through to the REST API, which caps at 100. - [x] Does the generated documentation in `docs/source/` reflect any of these limitations? — **No.** The generated docs simply mirror the Go source descriptions; fixing the Go source resolves the docs gap. - [x] Should a note be added explaining that results are always paginated and users must use `--page` to navigate, since true "list all" is intentionally not supported? — **Yes.** Folded into the new `--all` description. ## Outcome Addressed in [!3332](https://gitlab.com/gitlab-org/cli/-/merge_requests/3332). Applied flag-description updates: - `--all` → `"List all projects on the instance (removes ownership filter; results are still paginated — use --page to navigate)."` - `--per-page` → `"Number of items to list per page. Maximum: 100."` The MR also rolls the `Maximum: 100.` annotation out to every other command that exposes `--per-page` against a REST endpoint, for consistency (verified against the [GitLab REST API pagination docs](https://docs.gitlab.com/api/rest/#pagination): the 100 cap is universal across paginated endpoints). ## Proposed documentation changes If documentation updates are needed, the changes should be made in the Go source at `internal/commands/project/list/list.go` (not in `docs/source/` directly, per project conventions). Suggested flag description updates: - `--all`: Change from `"List all projects on the instance."` to something like `"List all projects on the instance (removes ownership filter; results are still paginated — use --page to navigate)."` - `--per-page`: Add the API maximum, e.g. `"Number of items to list per page. Maximum: 100."` (currently says `"Number of items to list per page."`) ## References - Original issue: [#8323 Unable to list all repositories in a single command. `--all` only returns partial results](https://gitlab.com/gitlab-org/cli/-/work_items/8323) - Source file: [`internal/commands/project/list/list.go`](https://gitlab.com/gitlab-org/cli/-/blob/main/internal/commands/project/list/list.go) - GitLab REST API pagination docs: [Keyset-based pagination](https://docs.gitlab.com/api/rest/#keyset-based-pagination) - [GitLab CLI documentation style guide](https://docs.gitlab.com/development/documentation/cli_styleguide/)