Authoring help on command classes that subclass aaz generated command class

[german1608]

Describe the bug

Not sure if it's a bug report, but none of the other categories felt right

I am working on an azure cli extension using aaz generated code. We want to write a custom command that subclasses one of these generated aaz commands.

from .aaz.latest.app import Update

class CustomUpdate(Update):
  ...

After registering in the command table, I noticed that the help message was inherited from the Update command. I then read authoring help guide and tried to add a help object for my command:

helps['app update'] = """
type: command
short-summary: Custom update logic
"""

But I was still getting the help message from the docstring of the Update command. I even tried adding the summary as a docstring of the CustomUpdate class, but still the same issue.

Then I discovered the AZ_HELP class variable, which I tried to set to the help string, and then I was able to see the expected message.

After some inspection, I learned that the reason was the @register_command decorator, which already generates AZ_HELP for that class, and also for my CustomUpdate class.

https://github.com/Azure/azure-cli/blob/dev/src/azure-cli-core/azure/cli/core/aaz/_command.py#L365-L370

After adding the @register_command annotation to my custom command (which does not register it to the command table) and using the regular docstring instead of AZ_HELP, I was able to see the help message correctly.

---

I think that we can just update the authoring help guide to account for this case. But at the same time I'd say is odd that using @register_command and also needing to register the command manually on the command table as this guide mentions is counterintuitive.

Not sure if there is a better way to figure this out, open to alternatives

Related command

Any --help of a subclass of an aaz command

Errors

No error, just incorrect output help message

Issue script & Debug output

Not relevant

Expected behavior

Not relevant

Environment Summary

azure-cli 2.78.0

core 2.78.0
telemetry 1.1.0

Extensions:
aks-preview 14.0.0b2
azure-devops 1.0.1
fleet 1.5.2
ip-group 1.0.1
k8s-extension 1.6.3
log-analytics-solution 1.0.1
virtual-wan 1.0.1
applink-preview 1.0.0b1 (dev) /home/gerobayopaz/azure-cli-extensions/src/applink-preview
k8s-extension 1.7.0 (dev) /home/gerobayopaz/azure-cli-extensions/src/k8s-extension

Dependencies:
msal 1.34.0b1
azure-mgmt-resource 23.3.0

Python location '/home/gerobayopaz/azure-cli-extensions/.venv/bin/python'
Config directory '/home/gerobayopaz/.azure'
Extensions directory '/home/gerobayopaz/.azure/cliextensions'
Development extension sources:
/home/gerobayopaz/azure-cli-extensions

Python (Linux) 3.10.12 (main, Aug 15 2025, 14:32:43) [GCC 11.4.0]

Additional context

No response

[yonzhan]

Thank you for opening this issue, we will look into it.

[necusjz]

thanks your detailed procedures! definitely, we'll add this as part of document.

i think the ideas behind we have to manually register again is we'd like to make each customization discoverable -> commands not in commands.py are directly generated -> easily debugging.