fix: allow CLI extensions to opt in to self-documented help

[pkey]

Pull Request Submission Checklist

• Follows CONTRIBUTING guidelines
• Commit messages
  are release-note ready, emphasizing
  what was changed, not how.
• Includes detailed description of changes
• Contains risk assessment (Low | Medium | High)
• Highlights breaking API changes (if applicable)
• Links to automated tests covering new functionality
• Includes manual testing instructions (if necessary)
• Updates relevant GitBook documentation (PR link: ___)
• Includes product update to be announced in the next stable release notes

What does this PR do?

Allows CLI extensions to opt in to handling --help via Cobra's flagset instead of TypeScript CLI's markdown-based help renderer.

This is opt-in for now and each command would need to have the annotation added if they want to use the Cobra native help.

Context

Currently, all help is routed through the legacy CLI which reads markdown files from help/cli-commands/ and renders them with a custom TypeScript pipeline. This couples extension help to external docs and means extensions cannot keep their documentation close to and true to the source code. This also adds the overhead of having to coordinate simple things like flag releases with the docs team.

This is a minimal, backwards-compatible change. Extensions opt in by adding a single annotation in the switch case in createCommandsForWorkflows(). No changes to go-application-framework or individual extension repos are required.

Extra considerations

• PROS: quicker help release cycle, smaller drift, especially when it comes to flags. This is important especially if agents are using our CLIs.
• CONS:
  • this would need a little extra plumbing to allow extensions defining Short/Long descriptions for richer help output.
  • not clear what would be the goal of the current help docs if extension switches

TODO

• if accepted by the team, this needs to be documented

Where should the reviewer start?

cliv2/cmd/cliv2/main.go — the prepareRootCommand() and createCommandsForWorkflows() functions.

How should this be manually tested?

1. Build the CLI: cd cliv2 && go build ./cmd/cliv2/
2. Run snyk redteam --help — should render Cobra-generated help from the flagset
3. Run snyk test --help — should still render the legacy markdown-based help (unchanged)

Example

What's the product update that needs to be communicated to CLI users?

N/A

Risk assessment: Low

• Only affects commands that explicitly opt in via the "self-documented" annotation
• All existing commands continue to use the legacy help pipeline
• No changes to external dependencies

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[pkey]

I ran a quick analysis of the current flag drift across most of the extensions and this is what I got:

test and monitor are probably not the best examples and still rely on legacy CLI for some flags. For us and others it would be a net positive.