STAC-24007: Remove repetitions from Usage descriptions

AGENTS.md

@@ -106,12 +106,10 @@ From CMD_DEVELOPMENT.md - critical rules for consistency:
 Per ADR 001: CLI `--help` output is the **authoritative source** for command documentation. External docs provide overviews only. This means help text must be self-sufficient, consistent, and include practical examples.
 
 ### Use Field Rules
-- **Noun-level commands**: `Use: "context"` (command appended automatically)
-- **Noun-verb commands**: `Use: "save --url URL {--api-token TOKEN | --service-token TOKEN}"`
-- **Required flags**: Show without brackets: `--url URL`
-- **Mutually exclusive required**: Group in `{}` with `|`: `{--api-token TOKEN | --service-token TOKEN}`
-- **Mutually exclusive optional**: Group in `[]` with `|`: `[--format JSON | --format YAML]`
-- **Flag values**: Use UPPER-CASE placeholders: `URL`, `TOKEN`, `FILE`
+- **IMPORTANT**: Do NOT include flags in the `Use` field. Required flags and mutually exclusive flag groups are **auto-generated** by `AddRequiredFlagsToUseString()` in `main.go` based on flag annotations set by `MarkMutexFlags()`. Including flags manually causes duplication in the help output.
+- **Noun-level commands**: `Use: "context"` (command name only)
+- **Noun-verb commands**: `Use: "delete"` (verb name only, no flags)
+- **Positional arguments only**: If the command takes positional arguments, include them: `Use: "describe [NAME]"`
 
 ### Short Field Rules
 - Start with **imperative verb** (Save, List, Delete, Show, Set, Validate)
@@ -162,7 +160,7 @@ sts context save --name ci-pipeline --url https://suse-observability.example.com
 
 ### Quality Checklist
 For every cobra.Command:
-- [ ] `Use` shows required flags and mutex groups correctly
+- [ ] `Use` contains only the command name
 - [ ] `Short` starts with verb, no period, adds context beyond command name
 - [ ] `Long` adds value beyond `Short`, ends with period, explains domain concepts
 - [ ] `Example` has 2-3 realistic, copy-pasteable examples with lowercase comments

cmd/context/context_delete.go

@@ -16,7 +16,7 @@ type DeleteArgs struct {
 func DeleteCommand(cli *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete --name NAME",
+		Use:   "delete",
 		Short: "Delete a saved context from the CLI configuration",
 		Long:  "Delete a connection context from the CLI configuration file. The currently active context cannot be deleted; switch to a different context first.",
 		Example: `# delete an unused context

cmd/context/context_save.go

@@ -30,7 +30,7 @@ type SaveArgs struct {
 func SaveCommand(cli *di.Deps) *cobra.Command {
 	args := &SaveArgs{}
 	cmd := &cobra.Command{
-		Use:   "save --url URL {--api-token TOKEN | --service-token TOKEN}",
+		Use:   "save",
 		Short: "Save a connection context to the CLI configuration",
 		Long:  `Save a connection context to the CLI configuration file. The context stores the server URL and authentication credentials. After saving, this context becomes the current active context.`,
 		Example: `# save a context with an API token

cmd/context/context_set.go

@@ -16,7 +16,7 @@ type SetArgs struct {
 func SetCommand(cli *di.Deps) *cobra.Command {
 	args := &SetArgs{}
 	cmd := &cobra.Command{
-		Use:   "set --name NAME",
+		Use:   "set",
 		Short: "Set the active context to use for CLI commands",
 		Long:  "Set the active connection context. All subsequent CLI commands will use this context's server URL and credentials.",
 		Example: `# switch to the production context

cmd/context/context_validate.go

@@ -14,7 +14,7 @@ type ValidateArgs struct {
 func ValidateCommand(cli *di.Deps) *cobra.Command {
 	args := &ValidateArgs{}
 	cmd := &cobra.Command{
-		Use:   "validate [--name NAME]",
+		Use:   "validate",
 		Short: "Validate that a context can connect to the server",
 		Long:  "Validate a connection context by attempting to connect to the SUSE Observability server. Validates the current context if no name is specified.",
 		Example: `# validate the current context

cmd/dashboard/dashboard_apply.go

@@ -21,7 +21,7 @@ type ApplyArgs struct {
 func DashboardApplyCommand(cli *di.Deps) *cobra.Command {
 	args := &ApplyArgs{}
 	cmd := &cobra.Command{
-		Use:   "apply --file FILE",
+		Use:   "apply",
 		Short: "Create or update a dashboard from a YAML file",
 		Long:  "Create or update a dashboard from a YAML file. If the YAML contains an 'id' field, the existing dashboard is updated; otherwise a new dashboard is created.",
 		Example: `# create a new dashboard from file

cmd/dashboard/dashboard_clone.go

@@ -22,14 +22,14 @@ type CloneArgs struct {
 func DashboardCloneCommand(cli *di.Deps) *cobra.Command {
 	args := &CloneArgs{}
 	cmd := &cobra.Command{
-		Use:   "clone {--id ID | --identifier URN} --name NAME",
+		Use:   "clone",
 		Short: "Clone an existing dashboard to create a new copy",
 		Long:  "Clone an existing dashboard to create a new copy with a different name. Optionally set a new description and scope for the cloned dashboard.",
 		Example: `# clone a dashboard by ID
 sts dashboard clone --id 123456789 --name My Dashboard Copy
 
 # clone a dashboard as private
-sts dashboard clone --identifier urn:stackpack:my-dashboard --name Private Copy --scope privateDashboard`,
+sts dashboard clone --identifier urn:stackpack:my-dashboard --name "Private Copy" --scope privateDashboard`,
 		RunE: cli.CmdRunEWithApi(RunDashboardCloneCommand(args)),
 	}
 

cmd/dashboard/dashboard_delete.go

@@ -19,7 +19,7 @@ type DeleteArgs struct {
 func DashboardDeleteCommand(cli *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete {--id ID | --identifier URN}",
+		Use:   "delete",
 		Short: "Delete a dashboard permanently",
 		Long:  "Delete a dashboard by its ID or identifier. Only user-owned dashboards can be deleted.",
 		Example: `# delete a dashboard by ID

cmd/dashboard/dashboard_describe.go

@@ -21,7 +21,7 @@ type DescribeArgs struct {
 func DashboardDescribeCommand(cli *di.Deps) *cobra.Command {
 	args := &DescribeArgs{}
 	cmd := &cobra.Command{
-		Use:   "describe {--id ID | --identifier URN}",
+		Use:   "describe",
 		Short: "Export a dashboard definition in YAML format",
 		Long:  "Export the full dashboard definition in YAML format. Output can be printed to stdout or saved to a file for backup or migration purposes.",
 		Example: `# describe a dashboard by ID

cmd/dashboard/dashboard_edit.go

@@ -21,7 +21,7 @@ type EditArgs struct {
 func DashboardEditCommand(cli *di.Deps) *cobra.Command {
 	args := &EditArgs{}
 	cmd := &cobra.Command{
-		Use:   "edit {--id ID | --identifier URN}",
+		Use:   "edit",
 		Short: "Edit a dashboard interactively in your default editor",
 		Long:  "Edit a dashboard interactively. Opens the dashboard YAML in the editor defined by your EDITOR environment variable. Changes are applied when you save and close the editor.",
 		Example: `# edit a dashboard by ID

cmd/health/health_clear_error.go

@@ -16,7 +16,7 @@ type ClearErrorArgs struct {
 func HealthClearErrorCommand(cli *di.Deps) *cobra.Command {
 	args := &ClearErrorArgs{}
 	cmd := &cobra.Command{
-		Use:   "clear-error --urn URN",
+		Use:   "clear-error",
 		Short: "Clear errors from a health synchronization stream",
 		Long: `Clear errors from a health synchronization stream, allowing it to resume normal operation. Use this after resolving the underlying cause of synchronization errors.
 

cmd/health/health_delete.go

@@ -16,7 +16,7 @@ type DeleteArgs struct {
 func HealthDeleteCommand(cli *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete --urn URN",
+		Use:   "delete",
 		Short: "Delete a health synchronization stream",
 		Long:  "Delete a health synchronization stream and all its sub-streams. This removes all check states associated with the stream.",
 		Example: `# delete a health stream

cmd/health/health_list.go

@@ -15,7 +15,7 @@ type ListArgs struct {
 func HealthListCommand(cli *di.Deps) *cobra.Command {
 	args := &ListArgs{}
 	cmd := &cobra.Command{
-		Use:   "list [--urn URN]",
+		Use:   "list",
 		Short: "List health synchronization streams or sub-streams",
 		Long:  "List all health synchronization streams. If a stream URN is provided, lists the sub-streams within that stream instead.",
 		Example: `# list all health streams

cmd/health/health_status.go

@@ -20,7 +20,7 @@ type StatusArgs struct {
 func HealthStatusCommand(cli *di.Deps) *cobra.Command {
 	args := &StatusArgs{}
 	cmd := &cobra.Command{
-		Use:   "status --urn URN",
+		Use:   "status",
 		Short: "Show detailed status of a health synchronization stream",
 		Long:  `Show detailed status of a health synchronization stream including metrics, errors, and consistency state. Use --sub-stream to check a specific sub-stream, or --topology to see topology element matches.`,
 		Example: `# show stream status

cmd/license/license_update.go

@@ -14,7 +14,7 @@ type UpdateArgs struct {
 func UpdateCommand(deps *di.Deps) *cobra.Command {
 	args := &UpdateArgs{}
 	cmd := &cobra.Command{
-		Use:   "update --key KEY",
+		Use:   "update",
 		Short: "Update the license with a new license key",
 		Long:  "Update the SUSE Observability license with a new license key. The new license takes effect immediately.",
 		Example: `# update the license

cmd/monitor/monitor_apply.go

@@ -18,7 +18,7 @@ type ApplyArgs struct {
 func MonitorApplyCommand(cli *di.Deps) *cobra.Command {
 	args := &ApplyArgs{}
 	cmd := &cobra.Command{
-		Use:   "apply --file FILE",
+		Use:   "apply",
 		Short: "Create or update a monitor from an STY file",
 		Long:  "Create or update a monitor from an STY (SUSE Observability YAML) file. If the monitor already exists, it will be updated.",
 		Example: `# apply a monitor definition

cmd/monitor/monitor_clone.go

@@ -18,7 +18,7 @@ type CloneArgs struct {
 func MonitorCloneCommand(cli *di.Deps) *cobra.Command {
 	args := &CloneArgs{}
 	cmd := &cobra.Command{
-		Use:   "clone {--id ID | --identifier URN} --name NAME",
+		Use:   "clone",
 		Short: "Clone an existing monitor to create an editable copy",
 		Long:  `Clone an existing monitor to create a new copy with a different name. This is useful for creating custom versions of locked monitors from StackPacks.`,
 		Example: `# clone a monitor by ID

cmd/monitor/monitor_delete.go

@@ -18,7 +18,7 @@ type DeleteArgs struct {
 func MonitorDeleteCommand(cli *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete {--id ID | --identifier URN}",
+		Use:   "delete",
 		Short: "Delete a monitor permanently",
 		Long:  "Delete a monitor by its ID or identifier. This removes the monitor and all its associated health states.",
 		Example: `# delete a monitor by ID

cmd/monitor/monitor_describe.go

@@ -19,7 +19,7 @@ type DescribeArgs struct {
 func MonitorDescribeCommand(cli *di.Deps) *cobra.Command {
 	args := &DescribeArgs{}
 	cmd := &cobra.Command{
-		Use:   "describe --id ID",
+		Use:   "describe",
 		Short: "Export a monitor definition in STY format",
 		Long:  "Export the monitor definition in STY (SUSE Observability YAML) format. Output can be printed to stdout or saved to a file for backup or migration.",
 		Example: `# describe a monitor to stdout

cmd/monitor/monitor_disable.go

@@ -13,7 +13,7 @@ import (
 func MonitorDisableCommand(cli *di.Deps) *cobra.Command {
 	args := &IdArgs{}
 	cmd := &cobra.Command{
-		Use:   "disable {--id ID | --identifier URN}",
+		Use:   "disable",
 		Short: "Disable a monitor to stop it from running",
 		Long:  "Disable a monitor to prevent it from running on its scheduled interval. A disabled monitor will not produce new health states.",
 		Example: `# disable a monitor by ID

cmd/monitor/monitor_edit.go

@@ -24,7 +24,7 @@ type EditArgs struct {
 func MonitorEditCommand(cli *di.Deps) *cobra.Command {
 	args := &EditArgs{}
 	cmd := &cobra.Command{
-		Use:   "edit {--id ID | --identifier URN}",
+		Use:   "edit",
 		Short: "Edit a monitor interactively in your default editor",
 		Long:  `Edit a monitor interactively. Opens the monitor definition in the editor defined by your VISUAL or EDITOR environment variable. Locked monitors (from StackPacks) require cloning first.`,
 		Example: `# edit a monitor by ID

cmd/monitor/monitor_enable.go

@@ -13,7 +13,7 @@ import (
 func MonitorEnableCommand(cli *di.Deps) *cobra.Command {
 	args := &IdArgs{}
 	cmd := &cobra.Command{
-		Use:   "enable {--id ID | --identifier URN}",
+		Use:   "enable",
 		Short: "Enable a disabled monitor to resume scheduled execution",
 		Long:  "Enable a disabled monitor to resume running on its configured schedule. The monitor will start producing health states again.",
 		Example: `# enable a monitor by ID

cmd/monitor/monitor_run.go

@@ -22,7 +22,7 @@ type RunArgs struct {
 func MonitorRunCommand(cli *di.Deps) *cobra.Command {
 	args := &RunArgs{}
 	cmd := &cobra.Command{
-		Use:   "run {--id ID | --identifier URN}",
+		Use:   "run",
 		Short: "Execute a monitor and display the results",
 		Long:  `Execute a monitor and display the results. By default runs in dry-run mode without saving health states. Use --yes to persist the resulting health states.`,
 		Example: `# dry-run a monitor (no state changes)

cmd/monitor/monitor_status.go

@@ -21,7 +21,7 @@ type StatusArgs struct {
 func MonitorStatusCommand(cli *di.Deps) *cobra.Command {
 	args := &StatusArgs{}
 	cmd := &cobra.Command{
-		Use:   "status {--id ID | --identifier URN}",
+		Use:   "status",
 		Short: "Show detailed runtime status of a monitor",
 		Long:  `Show detailed runtime status of a monitor including health state counts, stream metrics, errors, and topology matching results.`,
 		Example: `# show monitor status by ID

cmd/otelcomponentmapping/otelcomponentmapping_apply.go

@@ -20,7 +20,7 @@ type ApplyArgs struct {
 func OtelComponentMappingApplyCommand(deps *di.Deps) *cobra.Command {
 	args := &ApplyArgs{}
 	cmd := &cobra.Command{
-		Use:   "apply --file FILE",
+		Use:   "apply",
 		Short: "Create or edit an OTel Component Mapping from YAML",
 		Long:  "Create or edit a OTel Component Mapping from YAML file.",
 		Example: `# create a new OTel component mapping from a YAML file

cmd/otelcomponentmapping/otelcomponentmapping_delete.go

@@ -16,7 +16,7 @@ type DeleteArgs struct {
 func OtelComponentMappingDeleteCommand(deps *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete --identifier URN",
+		Use:   "delete",
 		Short: "Delete an OTel Component Mapping by identifier (URN)",
 		Long:  "Delete an OTel Component Mapping by identifier (URN)",
 		Example: `# delete a component mapping by identifier

cmd/otelcomponentmapping/otelcomponentmapping_describe.go

@@ -19,7 +19,7 @@ type DescribeArgs struct {
 func OtelComponentMappingDescribeCommand(deps *di.Deps) *cobra.Command {
 	args := &DescribeArgs{}
 	cmd := &cobra.Command{
-		Use:   "describe --identifier URN",
+		Use:   "describe",
 		Short: "Describe an Otel Component Mapping",
 		Long:  "Describe an Otel Component Mapping by identifier (URN). Optionally write to output file.",
 		Example: `# describe an OTel component mapping by identifier

cmd/otelcomponentmapping/otelcomponentmapping_edit.go

@@ -26,7 +26,7 @@ type EditArgs struct {
 func OtelComponentMappingEditCommand(deps *di.Deps) *cobra.Command {
 	args := &EditArgs{}
 	cmd := &cobra.Command{
-		Use:   "edit --identifier URN",
+		Use:   "edit",
 		Short: "Edit an OTel Component Mapping using $EDITOR",
 		Long:  LongDescription,
 		Example: `# edit a component mapping using your editor

cmd/otelrelationmapping/otelrelationmapping_apply.go

@@ -20,7 +20,7 @@ type ApplyArgs struct {
 func OtelRelationMappingApplyCommand(deps *di.Deps) *cobra.Command {
 	args := &ApplyArgs{}
 	cmd := &cobra.Command{
-		Use:   "apply --file FILE",
+		Use:   "apply",
 		Short: "Create or edit an OTel Relation Mapping from YAML",
 		Long:  "Create or edit an OTel Relation Mapping from YAML file.",
 		Example: `# create a new OTel relation mapping from a YAML file

cmd/otelrelationmapping/otelrelationmapping_delete.go

@@ -16,7 +16,7 @@ type DeleteArgs struct {
 func OtelRelationMappingDeleteCommand(deps *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete --identifier URN",
+		Use:   "delete",
 		Short: "Delete an OTel Relation Mapping by identifier (URN)",
 		Long:  "Delete an OTel Relation Mapping by identifier (URN).",
 		Example: `# delete a relation mapping by identifier

cmd/otelrelationmapping/otelrelationmapping_describe.go

@@ -19,7 +19,7 @@ type DescribeArgs struct {
 func OtelRelationMappingDescribeCommand(deps *di.Deps) *cobra.Command {
 	args := &DescribeArgs{}
 	cmd := &cobra.Command{
-		Use:   "describe --identifier URN",
+		Use:   "describe",
 		Short: "Describe an OTel Relation Mapping by identifier (URN)",
 		Long:  "Describe an OTel Relation Mapping by identifier (URN). Optionally write to output file.",
 		Example: `# describe an OTel relation mapping by identifier

cmd/otelrelationmapping/otelrelationmapping_edit.go

@@ -26,7 +26,7 @@ type EditArgs struct {
 func OtelRelationMappingEditCommand(deps *di.Deps) *cobra.Command {
 	args := &EditArgs{}
 	cmd := &cobra.Command{
-		Use:   "edit --identifier URN",
+		Use:   "edit",
 		Short: "Edit an OTel Relation Mapping using $EDITOR",
 		Long:  LongDescription,
 		Example: `# edit a relation mapping using your editor

cmd/rbac/rbac_create_subject.go

@@ -17,7 +17,7 @@ type CreateSubjectArgs struct {
 func CreateSubjectCommand(deps *di.Deps) *cobra.Command {
 	args := &CreateSubjectArgs{}
 	cmd := &cobra.Command{
-		Use:   "create-subject --subject SUBJECT",
+		Use:   "create-subject",
 		Short: "Create a new security subject",
 		Long:  "Create a new security subject for RBAC. Subjects can be users or groups that can be granted permissions.",
 		Example: `# create a new subject

cmd/rbac/rbac_delete_subject.go

@@ -15,7 +15,7 @@ type DeleteSubjectArgs struct {
 func DeleteSubjectCommand(deps *di.Deps) *cobra.Command {
 	args := &DeleteSubjectArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete-subject --subject SUBJECT",
+		Use:   "delete-subject",
 		Short: "Delete a security subject",
 		Long:  "Delete a security subject and revoke all its permissions. This operation cannot be undone.",
 		Example: `# delete a subject

cmd/rbac/rbac_describe_permissions.go

@@ -23,7 +23,7 @@ type DescribePermissionsArgs struct {
 func DescribePermissionsCommand(deps *di.Deps) *cobra.Command {
 	args := &DescribePermissionsArgs{}
 	cmd := &cobra.Command{
-		Use:   "describe-permissions --subject SUBJECT",
+		Use:   "describe-permissions",
 		Short: "Show permissions granted to a subject",
 		Long:  "Show all permissions granted to a subject. Can filter by permission type or resource.",
 		Example: `# show all permissions for a subject

cmd/rbac/rbac_grant.go

@@ -16,7 +16,7 @@ type GrantPermissionsArgs struct {
 func GrantPermissionsCommand(deps *di.Deps) *cobra.Command {
 	args := &GrantPermissionsArgs{}
 	cmd := &cobra.Command{
-		Use:   "grant --subject SUBJECT --permission PERMISSION",
+		Use:   "grant",
 		Short: "Grant a permission to a subject",
 		Long:  "Grant a permission to a subject on a resource. Use 'sts rbac list-permissions' to see available permissions.",
 		Example: `# grant access-view permission to all resources

cmd/rbac/rbac_revoke.go

@@ -16,7 +16,7 @@ type RevokePermissionsArgs struct {
 func RevokePermissionsCommand(deps *di.Deps) *cobra.Command {
 	args := &RevokePermissionsArgs{}
 	cmd := &cobra.Command{
-		Use:   "revoke --subject SUBJECT --permission PERMISSION",
+		Use:   "revoke",
 		Short: "Revoke a permission from a subject",
 		Long:  "Revoke a previously granted permission from a subject on a resource.",
 		Example: `# revoke access-view permission from all resources

cmd/script/script_run.go

@@ -27,7 +27,7 @@ const (
 func ScriptRunCommand(cli *di.Deps) *cobra.Command {
 	args := &ScriptRunArgs{}
 	cmd := &cobra.Command{
-		Use:   "run {--script SCRIPT | --file FILE}",
+		Use:   "run",
 		Short: "Execute an STSL script on the server",
 		Long:  "Execute an STSL (SUSE Observability Scripting Language) script on the server. Scripts can be provided inline or loaded from a file. Use --arguments-script to pass variables to the script.",
 		Example: `# run a script from file

cmd/servicetoken/servicetoken_create.go

@@ -25,7 +25,7 @@ type CreateArgs struct {
 func CreateCommand(deps *di.Deps) *cobra.Command {
 	args := &CreateArgs{}
 	cmd := &cobra.Command{
-		Use:   "create --name NAME --roles ROLES",
+		Use:   "create",
 		Short: "Create a new service token",
 		Long:  "Create a new service token for API authentication. The token is shown once upon creation and cannot be retrieved later.",
 		Example: `# create a token with admin role

cmd/servicetoken/servicetoken_delete.go

@@ -16,7 +16,7 @@ type DeleteArgs struct {
 func DeleteCommand(deps *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete --id ID",
+		Use:   "delete",
 		Short: "Delete a service token",
 		Long:  "Delete a service token by ID. This also removes any dedicated subject associated with the token.",
 		Example: `# delete a service token

cmd/settings/settings_apply.go

@@ -29,7 +29,7 @@ type ApplyArgs struct {
 func SettingsApplyCommand(cli *di.Deps) *cobra.Command {
 	args := &ApplyArgs{}
 	cmd := &cobra.Command{
-		Use:   "apply --file FILE",
+		Use:   "apply",
 		Short: "Import settings from an STY or STJ file",
 		Long:  "Import settings from an STY (SUSE Observability YAML) or STJ (SUSE Observability JSON) file. Can import to a specific namespace with conflict resolution strategies.",
 		Example: `# apply settings from file