Use custom usage template to avoid duplicate flag info in help output

[aravindtga]

Description

• What changed: Added a custom Cobra usage template that suppresses the auto-generated local Flags table for commands whose Long description already documents all flags. Updated Long descriptions across all leaf commands to ensure complete flag coverage, and fixed a pre-existing regression where pkg tree lost its Args section.
• Why it's needed: The help output for kpt leaf commands displayed flags twice, once in the curated Long description (with rich prose explanations) and again in Cobra's auto-generated terse flag table. This made help output unnecessarily long and confusing.
• How it works: The custom template checks if the command's Long description contains a "Flags:" section. If it does, the Cobra-generated local Flags table is suppressed. Global Flags are always shown. Commands without a "Flags:" section in their Long description (group commands, commands with no local flags) continue to render normally.

Before/After

Before (kpt fn render --help) - flags documented in Long description, then duplicated in Cobra's auto-generated table:

  Render a package.

    kpt fn render [PKG_PATH] [flags]

  Args:
    ...

  Flags:

    --allow-exec:
      Allow executable binaries to run as function. Note that executable binaries
      can perform privileged operations on your system, so ensure that binaries
      referred in the pipeline are trusted and safe to execute.

    --image-prefix:
      The container registry prefix to prepend to short image names...

    --output, o:
      If specified, the output resources are written to provided location...

    --results-dir:
      Path to a directory to write structured results...
    ...

  Usage:
    kpt fn render [PKG_PATH] [flags]

  Examples:
    ...

  Flags:
        --allow-alpha-wasm                    allow wasm to be used during pipeline execution.
        --allow-exec                          allow binary executable to be run during pipeline execution.
        --allow-network                       allow functions to access network during pipeline execution.
        -h, --help                                help for render
        --image-prefix string                 The prefix used when converting from short path to the full URL (defaults to $KPT_IMAGE_PREFIX if set) (default "ghcr.io/kptdev/krm-functions-catalog")
        --image-pull-policy ImagePullPolicy   pull image before running the container (one of Always, IfNotPresent, Never) (default IfNotPresent)
    -o, --output string                       output resources are written to provided location. Allowed values: stdout|unwrap|<OUT_DIR_PATH>
        --results-dir string                  path to a directory to save function results

  Global Flags:
        --truncate-output                     Enable the truncation for output (default true)
    -v, --v Level                             number for the log level verbosity

After - duplicate Cobra Flags table removed, only the curated documentation remains:

  Render a package.

    kpt fn render [PKG_PATH] [flags]

  Args:
    ...

  Flags:

    --allow-alpha-wasm:
      Allow wasm to be used during pipeline execution. When enabled, function
      images that are wasm modules will be executed using the wasm runtime
      instead of a container runtime. Defaults to false.

    --allow-exec:
      Allow executable binaries to run as function. Note that executable binaries
      can perform privileged operations on your system, so ensure that binaries
      referred in the pipeline are trusted and safe to execute.

    --image-prefix:
      The container registry prefix to prepend to short image names...

    --output, o:
      If specified, the output resources are written to provided location...

    --results-dir:
      Path to a directory to write structured results...
    ...

  Usage:
    kpt fn render [PKG_PATH] [flags]

  Examples:
    ...

  Global Flags:
        --truncate-output                     Enable the truncation for output (default true)
    -v, --v Level                             number for the log level verbosity

Group commands (e.g. kpt pkg --help) continue to show the Cobra flag table as before since they have no "Flags:" in their Long description.

Related Issue(s)

• Fixes Use Cobra SetHelpTemplate to avoid duplicate info in help output #439

Type of Change

• Enhancement
• Documentation

Checklist

• Code follows project style guidelines
• Self-reviewed changes
• Tests added/updated
• Documentation added/updated
• All tests and gating checks pass

AI Disclosure

• I have used AI in the creation of this PR.

If so, please describe how:
- Kiro to analyse the issue, identify gaps, implement the template change, and update all documentation.

[netlify]

✅ Deploy Preview for kptdocs ready!

Name	Link
🔨 Latest commit	425fda2
🔍 Latest deploy log	https://app.netlify.com/projects/kptdocs/deploys/6a5dfe0fc0b0d90009b27b59
😎 Deploy Preview	https://deploy-preview-4649--kptdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

This PR reduces duplication in kpt <cmd> --help output by introducing a custom Cobra usage template that conditionally suppresses Cobra’s auto-generated local Flags table when the command’s Long text already contains a curated Flags: section. It also updates generated CLI Long descriptions and the rendered documentation pages to ensure the curated sections fully cover each command’s flags/args (including restoring the missing pkg tree Args section).

Changes:

• Added a custom Cobra usage template (plus a template helper) to hide the auto local Flags table when Long includes Flags:, while always showing Global Flags.
• Updated generated command Long docs to include missing flag documentation for several commands (and restored kpt pkg tree Args content).
• Updated rendered CLI reference markdown pages to reflect the expanded/normalized Args/Flags sections.

Reviewed changes

Copilot reviewed 10 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
run/run.go	Adds custom Cobra usage template + template helper to suppress duplicate local flag tables when Long already contains Flags:.
internal/docs/generated/pkgdocs/docs.go	Updates generated pkg command docs to include complete Flags: / Args: content (e.g., cat, diff, tree).
internal/docs/generated/livedocs/docs.go	Updates generated live command docs to include missing flag entries (e.g., --status-policy, --quiet, --rg-file).
internal/docs/generated/fndocs/docs.go	Updates generated fn command docs to include missing flags and normalize formatting (e.g., --allow-alpha-wasm, selector flags).
documentation/content/en/reference/cli/pkg/tree/_index.md	Updates rendered docs for pkg tree Args section content and marker placement.
documentation/content/en/reference/cli/pkg/diff/_index.md	Adds rendered docs entry for --debug flag.
documentation/content/en/reference/cli/pkg/cat/_index.md	Normalizes rendered flag docs formatting and adds default-value notes.
documentation/content/en/reference/cli/live/migrate/_index.md	Adds rendered docs entry for --rg-file.
documentation/content/en/reference/cli/live/init/_index.md	Adds rendered docs entry for --quiet.
documentation/content/en/reference/cli/live/destroy/_index.md	Adds rendered docs entry for --status-policy.
documentation/content/en/reference/cli/live/apply/_index.md	Adds rendered docs entry for --status-policy.
documentation/content/en/reference/cli/fn/render/_index.md	Adds rendered docs entry for --allow-alpha-wasm.
documentation/content/en/reference/cli/fn/eval/_index.md	Adds rendered docs entries for --allow-alpha-wasm and match/exclude selector flags; fixes --match-kind formatting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.