( :book: ) [WiP] Enhancements to CLI Help by cmallikarjunah · Pull Request #5498 · kubernetes-sigs/kubebuilder

cmallikarjunah · 2026-02-22T17:03:33Z

Layout changes for better UX: Moved flag descriptions to Flags section i.e; to BindFlags() in the code. Some advantages of having detailed descriptions in Flags section:
1. Single Source of Truth - Flag description lives with flag definition
2. Less Duplication - Don't repeat flag info in two places
3. Better Maintenance - Update flag description in one place
4. Standard Practice - Matches how most CLI tools work (kubectl, git)
Issue: Enhancement: Review and improve flag descriptions, examples, and CLI help for better UX #5446

k8s-ci-robot · 2026-02-22T17:03:43Z

Hi @cmallikarjunah. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot · 2026-02-22T17:03:45Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: cmallikarjunah
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

camilamacedo86 · 2026-02-26T07:54:58Z

pkg/plugins/common/kustomize/v2/init.go

+	fs.StringVar(&p.domain, "domain", "my.domain", "[Required] Domain for API groups (e.g., example.org). "+
+		"This becomes the suffix for your API groups (e.g., crew.example.org/v1). "+
+		"Should be a domain you control. "+
+		"Cannot be changed after project initialization")


Thanks for taking a look! Where do you think we should add all this information for the flag?
Also, shouldn’t the flag text be concise?

@camilamacedo86 @cmallikarjunah I was testing it out and it seems that the short descriptions are too long, so the text ends up being truncated:

$ kubebuilder init -- --domain ([Required] Domain for API groups (e.g., example.org). This becomes the suffix for your API groups (e.g., crew.example.org/v1). Should be a domain you control. Cannot be changed after project…) --fetch-deps (download dependencies after scaffolding) --help (help for init) --license ([Configuration] license to use (apache2 or none, default: apache2)) --multigroup ([Layout] Enable multigroup layout to organize APIs by group. Scaffolds APIs in api/<group>/<version>/ instead of api/<version>/ Useful when managing multiple API groups (e.g., batch, apps, c…) --namespaced ([Layout] Enable namespace-scoped deployment instead of cluster-scoped (default: cluster-scoped). Manager watches one or more specific namespaces instead of all namespaces. Namespaces to watc…) --owner ([Configuration] copyright owner for license headers) --plugins (plugin keys to be used for this subcommand execution) --project-name (name of this project) --project-version (project version) --repo ([Configuration] Go module path (e.g., github.com/user/repo); auto-detected if not provided and project is initialized within $GOPATH) --skip-go-version-check (skip Go version check)

I suggest we keep the line lenght under 120 characters and don't use brackets to avoid polluting the message visually.

@camilamacedo86
I was trying to avoid duplication and to put info relating to each flag at one place. So I tried to accommodate all the flag description into its flag text. But I understand it may not look proper.

@vitorfloriano Thanks for verifying.

Will rework on this

camilamacedo86 · 2026-02-26T07:55:39Z

pkg/plugins/golang/v4/edit.go

-  Webhooks remain cluster-scoped even in namespace-scoped mode.
-  The manager cache is restricted to WATCH_NAMESPACE, but webhooks receive requests
-  from ALL namespaces. You must configure namespaceSelector or objectSelector to align
-  webhook scope with the cache.


I think we should keep the description here right?
Why we think that not?

camilamacedo86 · 2026-02-26T07:56:24Z

pkg/plugins/golang/v4/edit.go

+		"More info: https://book.kubebuilder.io/migration/namespace-scoped.html . ")
+	fs.BoolVar(&p.force, "force", false, "Overwrite existing scaffolded files to apply configuration changes. "+
+		"Example: With --namespaced, regenerates config/manager/manager.yaml to add WATCH_NAMESPACE env var. "+
+		"Warning: This overwrites default scaffold files; manual changes in those files may be lost.")


Shouldn’t the flag text be concise?
I am not sure, if this changes will make the UX better and ensure that we are following Cobra CLI best / common practices.

mayuka-c · 2026-03-01T13:42:15Z

pkg/plugins/golang/v4/init.go

 	fs.StringVar(&p.license, "license", "apache2",
-		"license header to use (apache2 or none)")
-	fs.StringVar(&p.owner, "owner", "", "copyright owner for license headers")
+		"[Configuration] license to use (apache2 or none, default: apache2)")


Just a small recommendation,
Maybe it would be better if we follow some format regarding the supported values and also default value it sets if not provided across all.

I was wondering maybe something like this
(apache2 | none) (default "apache2")

That should look good. Thanks for the suggestion @mayuka-c

mayuka-c · 2026-03-01T13:51:41Z

pkg/plugins/golang/v4/init.go

 	fs.BoolVar(&p.multigroup, "multigroup", false,
-		"enable multigroup layout (organize APIs by group)")
+		"[Layout] Enable multigroup layout to organize APIs by group. "+
+			"Scaffolds APIs in api/<group>/<version>/ instead of api/<version>/ "+
+			"Useful when managing multiple API groups (e.g., batch, apps, crew). ")


I guess the description of the flag should be limited to around 80 chars. This long description if required we can keep it in command help?

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Feb 22, 2026

k8s-ci-robot requested review from varshaprasad96 and vitorfloriano February 22, 2026 17:03

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 22, 2026

cmallikarjunah changed the title ~~(:book:) [WiP] Enhancements to CLI Help~~ ( 📖 ) [WiP] Enhancements to CLI Help Feb 22, 2026

cmallikarjunah mentioned this pull request Feb 24, 2026

Enhancement: Review and improve flag descriptions, examples, and CLI help for better UX #5446

Open

camilamacedo86 reviewed Feb 26, 2026

View reviewed changes

mayuka-c reviewed Mar 1, 2026

View reviewed changes

Update init.go

1941ec0

cmallikarjunah force-pushed the issue-5446-cli-help-enhancements branch from 5199364 to 1941ec0 Compare March 8, 2026 17:16

k8s-ci-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

( 📖 ) [WiP] Enhancements to CLI Help#5498

( 📖 ) [WiP] Enhancements to CLI Help#5498
cmallikarjunah wants to merge 1 commit intokubernetes-sigs:masterfrom
cmallikarjunah:issue-5446-cli-help-enhancements

cmallikarjunah commented Feb 22, 2026 •

edited

Loading

Uh oh!

k8s-ci-robot commented Feb 22, 2026

Uh oh!

k8s-ci-robot commented Feb 22, 2026

Uh oh!

camilamacedo86 Feb 26, 2026

Uh oh!

vitorfloriano Feb 26, 2026 •

edited

Loading

Uh oh!

cmallikarjunah Feb 27, 2026

Uh oh!

camilamacedo86 Feb 26, 2026

Uh oh!

camilamacedo86 Feb 26, 2026

Uh oh!

mayuka-c Mar 1, 2026

Uh oh!

cmallikarjunah Mar 2, 2026

Uh oh!

mayuka-c Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

cmallikarjunah commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Feb 22, 2026

Uh oh!

k8s-ci-robot commented Feb 22, 2026

Uh oh!

camilamacedo86 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

vitorfloriano Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmallikarjunah Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

mayuka-c Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

cmallikarjunah Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

mayuka-c Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cmallikarjunah commented Feb 22, 2026 •

edited

Loading

vitorfloriano Feb 26, 2026 •

edited

Loading