mmctl: Add support for listing user roles through mmctl

[Combs7th]

@claude - You are a senior technical writer triaging Engineering PRs for docs impact. Ask any clarifying questions.

MANDATORY SOURCE OF TRUTH
You MUST open and review the linked PR(s). If you have not reviewed them, stop and say: "review is required."

EVIDENCE RULE
All claims must map to explicit PR evidence (code/config/tests/comments/UI strings).
If not present, mark:
[NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT]

NON‑EDITABLE DOCS (HARD BLOCK)
DO NOT modify: changelogs, important upgrade notes, version archive, removed/deprecated features, unsupported legacy releases.

CAPABILITY ASSESSMENT (do this FIRST, before personas and priority)
Ask these questions before anything else:

1. What capability gap is closed? (e.g., "Mobile users couldn't access custom emojis, now they can")
2. Is this capability PARITY (closing a gap) or NET-NEW capability (something that never existed)?
3. Does the user's MENTAL MODEL change, or just the implementation?
4. What can users do now that they couldn't before? Answer in ONE sentence.

ANTI-PATTERNS (avoid over-engineering docs)
❌ DO NOT document implementation details: code structure, internal components, algorithms, technical architecture
BUT DO document admin-facing observability: log messages, metrics, events that admins use for operations/troubleshooting
❌ DO NOT document platform implementation differences when end-user action is identical
❌ DO NOT create execution prompts from code diffs—create them from capability changes
❌ DO NOT treat technical scope (files changed, new libraries, code complexity) as proxy for doc scope
❌ DO NOT assume big PR = big docs. 100 files changed can = 1 sentence doc update.
✅ DO ask: "What can users do now that they couldn't before?" Answer in ONE sentence
✅ DO document platform differences ONLY if users take different actions or see different outcomes
✅ DO default to minimal docs for capability parity—verify existing docs don't claim limitations, add version reference
✅ DO focus on user capability gain, not implementation details

OBSERVABILITY & DIAGNOSTICS (logging, metrics, events)
When PR adds logging, metrics, monitoring events, or diagnostic output:

• ✅ DO document if: Product has existing logging/metrics/observability reference documentation
• ✅ DO document if: Messages help admins troubleshoot or understand system behavior
• ✅ DO document if: New log levels, categories, or configuration options added
• ❌ DO NOT document if: Internal debug traces with no admin troubleshooting value
• ❌ DO NOT document if: Product has no logging documentation (implementation-only logs)

Check: Does the product documentation include:

• Log message reference / Log levels documentation?
• Troubleshooting guides that reference specific log messages?
• Metrics/monitoring documentation?

If YES: New observability output likely requires documentation update (typically P2/P3).
If NO: Logging changes are likely implementation details only.

Example - Document:

• "New DEBUG message: 'Skipping job X on non-leader node'" (helps admin troubleshooting in cluster deployments)
• "New metric: api_request_duration_seconds" (measurable system behavior for monitoring)
• "New audit log event: USER_PASSWORD_CHANGED" (security/compliance visibility)

Example - Don't Document:

• "Added trace logging to function processWidgets()" (internal debugging, no admin value)
• "Improved log formatting in module X" (implementation detail, output unchanged)

VERSION RULE
Extract milestone.title from PR metadata.
*If present → MUST use it in doc text (e.g., “From Mattermost vX.Y…”)
*If NOT present → use:
[NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT]

PERSONA MAP (use only when PR evidence applies)

• Operational Champion: prove solution, speed to value, adoption outcomes
• Economic Buyer: ROI, purchase justification, value proof
• System Admin: deploy/configure/operate safely
• IT Service Operations: onboarding/setup, standardize ops, minimize disruption
• Risk Assessor: security/compliance verification, liability risk
• End User: day‑to‑day workflow/usability
• System Integrator: integrations/tools/connectivity, automation, expert docs
  PERSONA INFERENCE RULES (evidence‑based; include persona only if PR changes success criteria)
• System Admin: changes to config defaults, admin settings, server behavior, admin APIs, maintenance, system behavior when config is missing, OR new log messages/metrics/events for troubleshooting/operations.
• IT Service Operations: onboarding, rollout/setup workflows, standardization, procedural runbooks.
• End User: UI/UX, end‑user workflows, client behavior, interactions, or user‑facing strings.
• System Integrator: APIs, webhooks, automation, integration tooling, SDKs, schema changes.
• Risk Assessor: security, compliance, audit, permissions, privacy, data handling.
• Operational Champion: adoption outcomes, enablement, measurable improvements.
• Economic Buyer: pricing/ROI claims, purchase justification, value outcomes.
  PHASE‑SENSITIVE DRAFTING (do NOT label the phase; use it to shape content)
• If PR affects defaults or runtime behavior: emphasize operational expectations, migration impact, and troubleshooting notes.
• If PR affects onboarding/setup: emphasize step‑by‑step setup, prerequisites, and rollout guidance.
• If PR affects error handling or UX confusion: emphasize "what changed," "why it happens," and "how to fix."
• If PR affects integrations/APIs: emphasize compatibility, request/response examples, and automation guidance.

DRAFTING PRINCIPLES

Write like official Mattermost docs:

• Clear, concise, and scannable
• No fluff or marketing language
• No speculation
• Use Mattermost tone (direct, instructional)
• Prefer updating existing sections over adding new ones
• Avoid redundancy with existing docs

SPECIAL DOC RULES

• New feature: include release intro as "From Mattermost vX.Y, you can …" only if PR evidence includes version. Otherwise: [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT].
• Deprecation: do not delete content. Mark deprecated from a specific release forward only if PR evidence includes version. Otherwise: [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT].
  Version from PR milestone
  Before drafting, you MUST read PR metadata (summary.json or PR API) and extract milestone.title. If a milestone exists, you MUST use that milestone version for any 'From Mattermost vX.Y' references and for the execution‑prompt lead‑in line, and you MUST cite the milestone field as evidence (e.g., summary.json: milestone.title). This overrides the 'version not present' rule. Only if the milestone is not present in PR metadata, explicitly state 'milestone not found in PR evidence' and mark the version as [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT].

REQUIRED STEPS

1. Review PR(s).
2. Answer CAPABILITY ASSESSMENT questions FIRST.
3. Identify user/admin/ops‑visible change (what they can DO, not what changed technically).
4. Assess risk if docs not updated.
5. Identify impacted personas (minimal set—fewer is better).

OUTPUT FORMAT (MUST MATCH EXACTLY)
=== CAPABILITY SUMMARY ===

• Capability change (one sentence):
• PARITY or NET-NEW:
• Docs scope: New / Update existing / None
• Target personas:

=== DOCUMENTATION DRAFT ===

Provide ONLY the doc-ready content.

Structure:

1. Recommended doc location

   • Specific page(s) OR “Identify likely pages”

2. Proposed content (ready to paste)

Use proper doc tone and formatting:

• Section headers (if needed)
• Short paragraphs
• Bullet points where appropriate
• Admin steps if applicable
• Troubleshooting notes if applicable

Include version reference ONLY if supported by PR evidence.

3. Notes (if needed)

• Call out assumptions
• Flag anything requiring SME validation:
  [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT]

---

FAIL CONDITIONS

If ANY of the following are true, STOP and say why:

• PR not reviewed
• No user/admin-visible change
• Change is purely internal or performance-only

---

HOW TO THINK

1. What can the user/admin DO now?
2. Where would they expect to read about it?
3. What is the smallest possible doc update that makes this clear?

[claude]

Claude finished @Combs7th's task in 24s —— View job

---

Docs Triage — Cannot Proceed

review is required.

This trigger was opened on an issue (#8964 — mmctl: Add support for listing user roles through mmctl), and the body does not link to any engineering PR. Per the MANDATORY SOURCE OF TRUTH rule, I cannot draft docs guidance without explicit PR evidence (code/config/tests/comments/UI strings).

What I need to proceed

Please reply with one of the following so I can run the docs‑impact assessment:

• Link the engineering PR(s) in mattermost/mattermost (or wherever the mmctl change lives) that implement listing user roles through mmctl. Example: mattermost/mattermost#NNNNN.
• If the change is not yet implemented, confirm this is a docs‑planning request only — in which case I'll mark version, scope, and most fields as [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] and produce a placeholder draft you can revise once code lands.
• If the PR is in a private or external repo I can't reach, paste the relevant code diff, command syntax, flags, and example output into a comment so I can evaluate against PR evidence.

Why I'm stopping here

The prompt explicitly forbids drafting from issue titles alone:

❌ DO NOT create execution prompts from code diffs — create them from capability changes
EVIDENCE RULE: All claims must map to explicit PR evidence.

Without the PR, I'd be inferring the command shape, flags, output format, permissions model, and version — all of which must come from PR evidence, not from the issue title.

Tasks

• Read issue body and check for linked PR
• Confirm no PR evidence available
• Awaiting PR link from @Combs7th before drafting capability summary and docs draft

---

· Branch: claude/issue-8964-20260512-1957

[Combs7th]

@claude - This is the PR link: mattermost/mattermost#34064

[claude]

Claude finished @Combs7th's task in 2m 4s —— View job

---

Docs Triage — Blocked on PR Fetch

Thanks @Combs7th — I received the PR link mattermost/mattermost#34064, but I cannot fetch it from this run. Every network/GitHub-API path I tried (gh pr view, gh api, curl, wget, WebFetch) is gated behind a permission prompt that I'm unable to auto-grant in this workflow.

Per the MANDATORY SOURCE OF TRUTH and EVIDENCE RULE in the triage prompt, I will not draft a docs update without reading the actual PR — inferring command syntax, flags, output, milestone, and permission model from the issue title alone would violate the rule.

Tasks

• Receive PR link from issue author
• Attempt to fetch PR 34064 (gh, curl, wget, WebFetch — all blocked by tool permissions in this run)
• Awaiting unblock — see options below
• Review code/test diffs for the new mmctl command
• Run CAPABILITY ASSESSMENT
• Identify recommended doc location in mattermost/docs
• Draft docs update

How to unblock me (pick one)

1. Re-trigger this workflow with network access for WebFetch or gh to github.com / api.github.com. The cleanest fix — the docs-triage logic itself works fine.
2. Paste the PR essentials in a reply and re-@claude. The minimum I need:
   • PR title and milestone (e.g., v10.x)
   • Exact new mmctl command/subcommand name (e.g., mmctl user roles list <user>)
   • Any new flags, their defaults, and short help text
   • Example invocation + sample output (one happy-path is enough)
   • Whether permissions/roles are required to run it (sysadmin? local mode only?)
   • Link to the new command file (e.g., server/cmd/mmctl/commands/user_roles.go) if you have it handy
3. If the change is still in progress, say so and I'll mark this issue as "docs planning pending PR merge" rather than draft now.

Why not just draft from the issue title?

The issue title says "Add support for listing user roles through mmctl" — that's a capability hint, not evidence. Without the PR I'd have to guess:

• Whether the command is mmctl user roles list, mmctl roles list-user-roles, mmctl user list --include-roles, or something else
• Whether output is human-readable, JSON, or both (and whether --json was added)
• Whether system + team + channel scheme roles are all included or only system roles
• Whether the milestone is v10.x, v11.x, or unset

All of those are exactly the fields the prompt requires me to cite PR evidence for. So I'd rather pause here than ship a draft that needs to be rewritten.

---

· Branch: claude/issue-8964-20260512-1959 ·

[Combs7th]

@claude - PR evidence for mattermost/mattermost#34064 below so you can proceed with docs triage.

PR title:
mmctl: Add support for listing user roles through mmctl

PR status:
Merged into mattermost:master on Mar 18, 2026.

Milestone:
v11.7.0

Docs label:
Docs/Needed

Capability summary:
This adds a new mmctl subcommand that lets admins list all available Mattermost roles.

Exact new command:
mmctl roles list

Command file:
server/cmd/mmctl/commands/roles.go

Command evidence:
RolesListCmd includes:

• Use: "list"
• Short: "List available roles"
• Example:
  $ mmctl roles list
  $ mmctl roles list --json
• Args: cobra.NoArgs
• RunE: withClient(rolesListCmdF)

Behavior:
rolesListCmdF calls GetAllRoles(context.TODO()). If that fails, it returns:
failed to get roles:

Output:
Plain output prints each role name using:
printer.PrintT("{{.Name}}", role)

JSON output:
The existing global --json flag is supported. Unit test confirms JSON behavior with test name:
"prints JSON list of all role objects"

Example roles from unit tests:
system_admin
system_user

Permissions:
E2E test runs successfully for:

• System admin
• Local mode

E2E test confirms non-privileged use fails:
"List roles without permissions should fail"
Expected error contains:
failed to get roles

Suggested docs location:
Update existing mmctl command reference:
source/administration-guide/manage/mmctl-command-line-tool.rst

Suggested doc-ready content:

mmctl roles list

From Mattermost v11.7.0, system admins can list all available roles using mmctl.

Format:

.. code-block:: text

   mmctl roles list [flags]

Examples:

.. code-block:: text

   mmctl roles list
   mmctl roles list --json

The command returns the available role names. Use ``--json`` to return role objects in JSON format.

Triage assessment:
Capability gap closed: System admins previously had mmctl commands to assign/revoke system admin roles, but no mmctl command to list available roles.
PARITY or NET-NEW: NET-NEW.
Mental model change: Minimal; this extends existing mmctl roles management with a discovery/list command.
What users can do now: System admins can list available Mattermost roles from mmctl before using role-related admin workflows.
Target persona: System Admin.
Docs scope: Update existing.
Risk if not documented: Admins won’t discover the new mmctl roles list command from the mmctl reference.

[claude]

Claude finished @Combs7th's task in 1m 54s —— View job • claude/issue-8964-20260512-2005 • Create PR ➔

---

Docs Triage — Complete

Thanks @Combs7th — PR evidence accepted for mattermost/mattermost#34064 (milestone v11.7.0, merged 2026‑03‑18). Triage and draft below; file change committed to branch.

Tasks

• Receive PR evidence from issue author
• Locate source/administration-guide/manage/mmctl-command-line-tool.rst (parent mmctl roles section at line 5679; insertion point before mmctl saml at line 5746)
• Confirm heading conventions (parent -----, child ~~~~~ — matches mmctl saml auth-data-reset pattern)
• Produce CAPABILITY SUMMARY + DOCUMENTATION DRAFT
• Add new mmctl roles list subsection to the reference doc
• Commit and push to branch

---

=== CAPABILITY SUMMARY ===

• Capability change (one sentence): System admins can now list all available Mattermost roles from the command line with mmctl roles list, in plain or JSON output.
• PARITY or NET-NEW: NET-NEW (no prior mmctl listing of roles existed; previously only assign/unassign of system_admin/member was available via mmctl roles).
• Docs scope: Update existing.
• Target personas: System Admin (sole impacted persona — discovery of role names for admin workflows; no end-user UI change).

---

=== DOCUMENTATION DRAFT ===

1) Recommended doc location

• source/administration-guide/manage/mmctl-command-line-tool.rst — insert a new ~~~~~ subsection mmctl roles list after the existing mmctl roles block (parent section starts at line 5679) and before mmctl saml (line 5746). This matches the structural pattern used by mmctl saml → mmctl saml auth-data-reset.

2) Proposed content (committed in this branch)

mmctl roles list
~~~~~~~~~~~~~~~~

**Description**

From Mattermost v11.7.0, list all available roles. System admins can use this command to discover role names (for example, ``system_admin`` or ``system_user``) before assigning or unassigning roles with other mmctl commands. Requires system admin privileges or local mode.

**Format**

.. code-block:: sh

   mmctl roles list [flags]

**Examples**

.. code-block:: sh

   # List the names of all available roles.
   $ mmctl roles list

   # Return all role objects in JSON format.
   $ mmctl roles list --json

**Options**

.. code-block:: sh

   -h, --help   help for list

**Options inherited from parent commands**

.. code-block:: sh

   --config string                path to the configuration file (default "$XDG_CONFIG_HOME/mmctl/config")
   --disable-pager                disables paged output
   --insecure-sha1-intermediate   allows to use insecure TLS protocols, such as SHA-1
   --insecure-tls-version         allows to use TLS versions 1.0 and 1.1
   --json                         the output format will be in json format
   --local                        allows communicating with the server through a unix socket
   --quiet                        prevent mmctl to generate output for the commands
   --strict                       will only run commands if the mmctl version matches the server one
   --suppress-warnings            disables printing warning messages

3) Notes

• Version v11.7.0 is sourced from PR milestone metadata (cited in trigger comment as milestone: v11.7.0) and used in the "From Mattermost v11.7.0…" lead-in per the SPECIAL DOC RULES.
• Permissions wording ("system admin privileges or local mode") is supported by the E2E evidence ("List roles without permissions should fail" + GetAllRoles succeeds for sysadmin and local mode).
• -h, --help help for list assumes the standard cobra help flag for child commands. [NOT PRESENT IN PR EVIDENCE — REQUIRES HUMAN JUDGMENT if the exact help string differs.]
• Out of scope (not changed): I did not refactor the existing mmctl roles parent block to add a "Child Commands" listing (as mmctl saml does). That would be a separate consistency improvement; flagging it for SME review.
• Anti-pattern check: Did not document implementation details (GetAllRoles, printer.PrintT template, RolesListCmd struct) — these are internal. Did document admin-facing capability + permissions + version, per the triage rules.

---

Diff summary

source/administration-guide/manage/mmctl-command-line-tool.rst — +43 / -0 lines. New mmctl roles list subsection inserted between the existing mmctl roles block and mmctl saml.

---

· Branch: claude/issue-8964-20260512-2005

[Combs7th]

@claude - Please review the mmctl roles list docs update using two lenses:

1. Novice Nate: Is anything too complex, assumed, or unclear for a newer Mattermost admin who may not be deeply familiar with mmctl, roles, JSON output, or local mode? Flag only issues that would likely confuse a novice admin.

2. Editor Evie: Check wording, concision, formatting, and consistency with surrounding Mattermost docs. Suggest only necessary edits.

Please keep feedback brief and actionable. Do not expand the scope beyond this new mmctl roles list section.

[claude]

Claude finished @Combs7th's task in 1m 14s —— View job

---

Docs Review — mmctl roles list

Two-lens review of the new subsection committed to claude/issue-8964-20260512-2005. I compared against the surrounding mmctl roles parent block (line 5679) and the structurally similar mmctl saml auth-data-reset subsection (line 5760) in the same file.

Tasks

• Read the proposed mmctl roles list subsection
• Check surrounding sections for style/format consistency
• Apply Novice Nate lens
• Apply Editor Evie lens
• Post brief, actionable feedback

---

Novice Nate (newer admin) — 2 flags

1. "or local mode" is unexplained. A newer admin reading the Description sentence ("Requires system admin privileges or local mode") won't know what local mode is or how to enter it. The --local flag description in the inherited options block ("allows communicating with the server through a unix socket") doesn't really clarify it either. Suggest linking the phrase to the existing local mode docs the first time it appears, e.g.:

   Requires system admin privileges, or :ref:local mode <administration-guide/manage/mmctl-command-line-tool:local mode setup>.
   (Confirm the exact anchor — the doc has a "Local mode setup" / "Working in local mode" section earlier; SME to validate the target.)

2. Permission requirement is buried at the end of the Description. A novice admin scans for "do I have permission to run this?" and is more likely to find it as a callout than as the last clause of a three-clause sentence. Suggest pulling it out — either into its own short paragraph after the Description, or as a .. note:: directive. Surrounding mmctl entries don't all do this, so it's optional, but it's the highest-value clarity fix for novices.

Not flagging: system_user role naming, --json output shape — these are reasonable knowledge expectations for anyone already running mmctl, and the surrounding sections don't explain them either.

---

Editor Evie — 3 small edits

1. Lead-in reads awkwardly. "From Mattermost v11.7.0, list all available roles." uses bare imperative after the version clause. Either:

   • "From Mattermost v11.7.0, you can list all available roles." (matches the conversational lead-in style used elsewhere in the admin guide), or
   • Drop the lead-in from the Description and add a short "New in v11.7.0." prefix, similar to other versioned features.

2. Example comment punctuation is inconsistent with the comparator. The new section's inline comments end in periods:

   # List the names of all available roles.
   # Return all role objects in JSON format.
   

   The structurally identical mmctl saml auth-data-reset block (line 5777) uses no trailing period:

   # Reset all SAML users' AuthData field to their email, including deleted users
   

   Drop the periods to match local convention.

3. Parallel the two example comments. "List the names…" vs "Return all role objects…" mixes verbs. Suggest:

   # List all available role names
   # List all available role objects in JSON format
   

---

Out of scope (flagging only, not asking for a fix here)

• The parent mmctl roles block (line 5679) now has a child command but no Child Commands listing — unlike mmctl saml (line 5751) which lists mmctl saml auth-data-reset. Adding - mmctl roles list_ - List available roles under mmctl roles would improve discoverability and match house style. The prior comment already flagged this for SME review; noting again so it isn't lost.

---

Summary

The draft is accurate and structurally correct. Two novice-focused tweaks (link/clarify local mode; surface the permission requirement) and three style tweaks (lead-in phrasing, comment punctuation, parallel verb forms) are all I'd recommend before merge.
· Branch under review: claude/issue-8964-20260512-2005

[Combs7th]

@claude - Implement the suggested fixes from Novice Nate and Editor Evie.

[claude]

Claude finished @Combs7th's task in 1m 36s —— View job • claude/issue-8964-20260512-2016 • Create PR ➔

---

Review Fixes Applied — mmctl roles list

Implemented the Novice Nate and Editor Evie suggestions and committed to claude/issue-8964-20260512-2016.

Tasks

• Read the current mmctl roles list subsection on this branch
• Locate the correct local-mode anchor for the cross-reference (#local-mode, matches the established local mode <#local-mode> pattern used on lines 22, 2493, 4266, 7053)
• Apply Novice Nate fixes (link "local mode"; surface permission requirement)
• Apply Editor Evie fixes (lead-in phrasing; example comment punctuation; parallel verbs)
• Commit and push to branch

---

Changes made

Novice Nate

1. "local mode" is now linked. Uses the same `local mode <#local-mode>`__ form already used elsewhere in this file (e.g., line 22, 2493, 4266, 7053), so no SME validation needed on the anchor.
2. Permission requirement surfaced in a .. note:: directive right after the Description, so a novice admin scanning for "do I have permission to run this?" sees it without parsing a multi-clause sentence.

Editor Evie

1. Lead-in reworded from "From Mattermost v11.7.0, list all available roles." → "From Mattermost v11.7.0, you can list all available roles."
2. Trailing periods removed from the inline example comments, matching the convention used by mmctl saml auth-data-reset (line 5777).
3. Parallel verb forms — both example comments now start with "List":
   • # List all available role names
   • # List all available role objects in JSON format

Out of scope (deliberately not touched)

• Did not modify the parent mmctl roles block to add a "Child Commands" listing — the trigger asked to keep scope to the new subsection only. Flagging once more for the next review pass.

---

Final subsection (committed)

mmctl roles list
~~~~~~~~~~~~~~~~

**Description**

From Mattermost v11.7.0, you can list all available roles. System admins can use this command to discover role names (for example, ``system_admin`` or ``system_user``) before assigning or unassigning roles with other mmctl commands.

.. note::

   This command requires system admin privileges, or `local mode <#local-mode>`__.

**Format**

.. code-block:: sh

   mmctl roles list [flags]

**Examples**

.. code-block:: sh

   # List all available role names
   $ mmctl roles list

   # List all available role objects in JSON format
   $ mmctl roles list --json

**Options**

.. code-block:: sh

   -h, --help   help for list

**Options inherited from parent commands**

.. code-block:: sh

   --config string                path to the configuration file (default "$XDG_CONFIG_HOME/mmctl/config")
   --disable-pager                disables paged output
   --insecure-sha1-intermediate   allows to use insecure TLS protocols, such as SHA-1
   --insecure-tls-version         allows to use TLS versions 1.0 and 1.1
   --json                         the output format will be in json format
   --local                        allows communicating with the server through a unix socket
   --quiet                        prevent mmctl to generate output for the commands
   --strict                       will only run commands if the mmctl version matches the server one
   --suppress-warnings            disables printing warning messages

---

Diff summary

source/administration-guide/manage/mmctl-command-line-tool.rst — +47 / -0 lines. New mmctl roles list subsection inserted between the existing mmctl roles block and mmctl saml.

---

· Branch: claude/issue-8964-20260512-2016 ·

[Combs7th]

@claude - This looks good for review overall. Please make one final evidence-safety cleanup: remove the child-specific Options block containing -h, --help help for list unless that exact generated help output was verified from the command. The inherited options section can stay.

Optional wording cleanup: simplify the Description to avoid implying a workflow beyond the PR evidence:

“From Mattermost v11.7.0, you can list all available roles and discover role names, such as system_admin or system_user.”

Keep the note, examples, local mode link, and inherited options as-is.

[claude]

Claude finished @Combs7th's task in 1m 12s —— View job • claude/issue-8964-20260512-2020 • Create PR ➔

---

Final Evidence-Safety Cleanup Applied — mmctl roles list

Committed and pushed to claude/issue-8964-20260512-2020.

Tasks

• Read trigger comment and confirm scope (drop child Options block; simplify Description; keep note/examples/local-mode link/inherited options)
• Verify current branch state (fresh from master — applied prior Novice Nate + Editor Evie fixes plus the new cleanup in one commit)
• Locate insertion point (between mmctl roles at line 5679 and mmctl saml at line 5746)
• Insert revised mmctl roles list subsection
• Commit and push to branch

---

Changes in this commit

Trigger fixes (this pass)

1. Dropped child-specific Options block. The -h, --help help for list line was not verified from the PR evidence — removed per the evidence-safety rule. The Options inherited from parent commands block stays as-is.
2. Description simplified to the wording you provided:

   From Mattermost v11.7.0, you can list all available roles and discover role names, such as system_admin or system_user.
   This avoids implying a workflow ("before assigning or unassigning roles with other mmctl commands") that wasn't established in PR evidence.

Carried forward from the prior review pass (since this branch is fresh from master)

• local mode is linked using the file-local `local mode <#local-mode>`__ form already used elsewhere in this doc.
• Permission requirement surfaced in a .. note:: directive immediately after the Description.
• Example comments use parallel List … phrasing with no trailing periods, matching the local convention from mmctl saml auth-data-reset.

---

Final subsection (committed)

mmctl roles list
~~~~~~~~~~~~~~~~

**Description**

From Mattermost v11.7.0, you can list all available roles and discover role names, such as ``system_admin`` or ``system_user``.

.. note::

   This command requires system admin privileges, or `local mode <#local-mode>`__.

**Format**

.. code-block:: sh

   mmctl roles list [flags]

**Examples**

.. code-block:: sh

   # List all available role names
   $ mmctl roles list

   # List all available role objects in JSON format
   $ mmctl roles list --json

**Options inherited from parent commands**

.. code-block:: sh

   --config string                path to the configuration file (default "$XDG_CONFIG_HOME/mmctl/config")
   --disable-pager                disables paged output
   --insecure-sha1-intermediate   allows to use insecure TLS protocols, such as SHA-1
   --insecure-tls-version         allows to use TLS versions 1.0 and 1.1
   --json                         the output format will be in json format
   --local                        allows communicating with the server through a unix socket
   --quiet                        prevent mmctl to generate output for the commands
   --strict                       will only run commands if the mmctl version matches the server one
   --suppress-warnings            disables printing warning messages

---

Diff summary

source/administration-guide/manage/mmctl-command-line-tool.rst — +41 / -0 lines. New mmctl roles list subsection inserted between mmctl roles and mmctl saml.

---

· Branch: claude/issue-8964-20260512-2020 ·