fix: improve CLI flag descriptions and help text for create api command by yosofbadr · Pull Request #5628 · kubernetes-sigs/kubebuilder

yosofbadr · 2026-04-15T19:24:54Z

Summary

Addresses #5446 by improving the CLI help UX for the create api command and shared flags.

Rewrite create api long description with organized flag categories (required, resource, controller, external API) so users can quickly find what they need
Replace generic examples (which included raw nano and make steps) with actionable kubebuilder examples covering common workflows: resource-only, controller-only, cluster-scoped, multiple controllers, and external API scaffolding
Make all flag descriptions concise (under 80 chars), with lowercase start and consistent phrasing -- addressing reviewer feedback from ( 📖 ) Enhancements to CLI Help #5498
Add inline examples to shared flags (--group, --version, --kind, --plugins, --project-version) for discoverability

Following the maintainer's suggestion in #5498 to submit small, focused PRs per command.

Files changed

pkg/plugins/golang/v4/api.go -- main improvements to create api description, examples, and flag text
pkg/cli/resource.go -- improved --group, --version, --kind flag descriptions (shared by create api and create webhook)
pkg/cli/root.go -- improved --plugins and --project-version flag descriptions
pkg/cli/init.go -- improved --project-version flag description (init-specific registration)

Test plan

go build ./... passes
go test ./pkg/cli/... passes
go test ./pkg/plugins/golang/v4/... passes
Verify kubebuilder create api --help output reads well in a terminal
Verify flag descriptions are not truncated in tab-completion output

linux-foundation-easycla · 2026-04-15T19:25:02Z

The committers listed above are authorized under a signed CLA.

✅ login: yosofbadr / name: Yosof Badr (e7955f1)

k8s-ci-robot · 2026-04-15T19:25:02Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: yosofbadr
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

k8s-ci-robot · 2026-04-15T19:25:04Z

Welcome @yosofbadr!

It looks like this is your first PR to kubernetes-sigs/kubebuilder 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/kubebuilder has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2026-04-15T19:25:05Z

Hi @yosofbadr. 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.

camilamacedo86 · 2026-04-16T05:49:02Z


-  # Generate the manifests
-  make manifests
+  # Add a second controller for an existing resource


Suggested change

# Add a second controller for an existing resource

# Add a controller for an existing resource

It might be the second or not
Example, I scaffold the API only ( controller=false ) then I scaffold the controller only

camilamacedo86 · 2026-04-16T05:54:55Z

Very nice work 🎉
Just added some comments

Address review feedback on the create api help text: - Replace "Scaffold" with "Create" in command descriptions and the long-form help, matching the subcommand name and the preferred wording. - Standardize boolean flag descriptions with the "If set, ... Default: ..." pattern for --make, --force, --resource, --namespaced, and --controller. - Add examples for the common "create a controller for an existing resource" and "controller for an external API" flows, which were previously undocumented. Signed-off-by: Yosof Badr <23705518+YosofBadr@users.noreply.github.com>

yosofbadr · 2026-04-21T19:50:36Z

Thanks @camilamacedo86 for the detailed review — I've pushed e7955f1 addressing the feedback:

"Create" vs "Scaffold": Replaced Scaffold with Create in pkg/plugins/golang/v4/api.go (UpdateMetadata description) as well as in pkg/cli/api.go and pkg/cli/create.go so the wording is consistent across the command hierarchy.
Boolean flag standard: All booleans in BindFlags (--make, --force, --resource, --namespaced, --controller) now follow the If set, ... Default: ... pattern.
"Add a second controller" example: Reworded to Add a controller for an existing resource (e.g., an additional reconciler) — reads more naturally without implying ordering. Also added a concrete --external-api-* example since that flow was previously undocumented.

Note: the upstream changes to pkg/cli/resource.go, pkg/cli/root.go, and pkg/cli/init.go already landed what this PR originally proposed there, so the diff is now focused on api.go + the two small cli/*.go wording tweaks.

The build and ./pkg/cli/... / ./pkg/plugins/golang/v4/... tests pass locally. Ready for another look whenever you have a moment.

Copilot

Pull request overview

Improves the kubebuilder create api help UX by updating command descriptions, examples, and several flag help strings to be more discoverable and consistent across the CLI.

Changes:

Updates create api long description and examples, including external API/controller workflows.
Rewrites several create api flag descriptions (--make, --resource, --namespaced, --controller) for clarity.
Adjusts create / create api CLI Short/Long help text terminology (“Scaffold” → “Create”).

Reviewed changes

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

Show a summary per file

File	Description
pkg/plugins/golang/v4/api.go	Updates `create api` metadata (description/examples) and several flag help strings.
pkg/cli/create.go	Updates `create` command Short/Long help text wording.
pkg/cli/api.go	Updates `create api` command Short/Long help text wording.
pkg/cli/resource.go	Updates shared `--group/--version/--kind` flag descriptions for better examples/discoverability.
pkg/cli/root.go	Updates shared `--plugins` / `--project-version` flag descriptions.
pkg/cli/init.go	Updates `--project-version` flag description for init command registration.

Comments suppressed due to low confidence (1)

pkg/plugins/golang/v4/api.go:100

PR description says the help examples were updated to replace raw editor/make steps, but the examples still include nano ... and several make ... commands below. Either update the PR description or revise these examples to match the stated goal.

  # Edit the API Scheme
  nano api/v1beta1/frigate_types.go

  # Edit the Controller
  nano internal/controller/frigate/frigate_controller.go

  # Edit the Controller Test
  nano internal/controller/frigate/frigate_controller_test.go

  # Generate the manifests
  make manifests

  # Install CRDs into the Kubernetes cluster using kubectl apply
  make install

  # Regenerate code and run against the Kubernetes cluster configured by ~/.kube/config
  make run

Copilot · 2026-04-22T05:38:12Z

+After the files are created, the dependencies will be updated and
 make generate will be run.


The long description says "make generate will be run", but PostScaffold only runs make generate when --make is true and the resource has an API (p.resource.HasAPI()). Please adjust the wording to reflect the conditional behavior (and/or mention the --make=false opt-out).

Suggested change

After the files are created, the dependencies will be updated and

make generate will be run.

After the files are created, the dependencies will be updated.

If --make is not set to false and the resource has an API,

make generate will also be run.

Copilot · 2026-04-22T05:38:12Z

+After the files are created, the dependencies will be updated and
 make generate will be run.
 `
 	subcmdMeta.Examples = fmt.Sprintf(`  # Create a frigates API with Group: ship, Version: v1beta1 and Kind: Frigate


Typo in example text: "a frigates API" should be singular ("a frigate API").

Suggested change

subcmdMeta.Examples = fmt.Sprintf(` # Create a frigates API with Group: ship, Version: v1beta1 and Kind: Frigate

subcmdMeta.Examples = fmt.Sprintf(` # Create a frigate API with Group: ship, Version: v1beta1 and Kind: Frigate

Copilot · 2026-04-22T05:38:12Z

 	fs.BoolVar(&p.runMake, "make", true,
-		"Run 'make generate' after generating files (enabled by default; use --make=false to disable)")
+		"If set, run 'make generate' after creating files. Default: true. "+
+			"Use --make=false to skip running make generate")


--make help text is written as "If set... Default: true" but this flag is default-true (opt-out) and the repo's CLI description standards recommend phrasing like "Run ... (enabled by default; use --make=false to disable)". Also note that make generate only runs when p.resource.HasAPI(); the current wording implies it always runs after creating files.

Copilot · 2026-04-22T05:38:13Z

+		"If set, create the resource without prompting. Default: true. "+
+			"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API)")


--resource help text says it will create the resource "without prompting" and that the default is true, but the implementation prompts when the flag isn't explicitly set (if !p.resourceFlag.Changed { ... util.YesNo(...) }). The wording should reflect the prompting behavior (see .agents/skills/cli-descriptions/SKILL.md:83-94 for the recommended pattern).

Suggested change

"If set, create the resource without prompting. Default: true. "+

"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API)")

"If set, create the resource. "+

"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API). "+

"If not specified, you may be prompted to confirm whether to create the resource")

Copilot · 2026-04-22T05:38:13Z

+		"If set, create a namespaced resource. Default: true. "+
+			"Use --namespaced=false to create a cluster-scoped resource")


--namespaced help text uses the "If set... Default: true" pattern, but this is a default-true (opt-out) flag. The repo's CLI description standards recommend phrasing like "Resource is namespaced by default; use --namespaced=false to create a cluster-scoped resource" (.agents/skills/cli-descriptions/SKILL.md:48-68).

Suggested change

"If set, create a namespaced resource. Default: true. "+

"Use --namespaced=false to create a cluster-scoped resource")

"Resource is namespaced by default; use --namespaced=false to create a cluster-scoped resource")

Copilot · 2026-04-22T05:38:13Z

+		Short:      "Create a Kubernetes API or webhook",
+		Long: fmt.Sprintf(`Create a Kubernetes API or webhook.


This changes the create command help from "Scaffold" to "Create", but related subcommands (e.g., create webhook) still use "Scaffold" in their Short/Long help (see pkg/cli/webhook.go:33-35). Consider using consistent terminology across create and its subcommands to avoid confusing users.

Suggested change

Short: "Create a Kubernetes API or webhook",

Long: fmt.Sprintf(`Create a Kubernetes API or webhook.

Short: "Scaffold a Kubernetes API or webhook",

Long: fmt.Sprintf(`Scaffold a Kubernetes API or webhook.

I think Scaffold was a good suggestion.
I think we changed that see that acrros the project, we have a skill as well now: https://github.com/kubernetes-sigs/kubebuilder/tree/master/.agents/skills/cli-descriptions

Copilot · 2026-04-22T05:38:13Z

+		Short: "Create a Kubernetes API",
+		Long:  `Create a Kubernetes API by writing a Resource definition and/or a Controller.`,


create api Short/Long help now uses "Create", while create webhook still uses "Scaffold" (pkg/cli/webhook.go:33-35). Consider aligning the terminology across create subcommands for a consistent help UX.

Suggested change

Short: "Create a Kubernetes API",

Long: `Create a Kubernetes API by writing a Resource definition and/or a Controller.`,

Short: "Scaffold a Kubernetes API",

Long: `Scaffold a Kubernetes API by writing a Resource definition and/or a Controller.`,

Copilot · 2026-04-22T05:38:14Z

-  # Edit the API Scheme
+  # Add a controller for an existing resource (e.g., an additional reconciler)
+  %[1]s create api --group ship --version v1beta1 --kind Frigate \
+      --resource=false --controller-name frigate-status


The "add a controller" example omits --controller=true, so it will prompt interactively by default (since the code prompts when the flag isn't explicitly set). Consider making the example non-interactive by including an explicit --controller=true (and similarly any other prompting flags).

Suggested change

--resource=false --controller-name frigate-status

--resource=false --controller=true --controller-name frigate-status

Copilot · 2026-04-22T05:38:14Z

+		"If set, create the controller. Default: true. "+
+			"Use --controller=false to skip controller creation")


--controller help text says "Default: true" and suggests --controller=false to skip creation, but the command prompts when the flag isn't explicitly set (if !p.controllerFlag.Changed { ... }). Please use the prompting-flag wording (e.g., "Prompt whether to generate the controller by default; use --controller=true or --controller=false to skip the prompt") per .agents/skills/cli-descriptions/SKILL.md:83-94.

Suggested change

"If set, create the controller. Default: true. "+

"Use --controller=false to skip controller creation")

"Prompt whether to generate the controller by default; "+

"use --controller=true or --controller=false to skip the prompt")

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. labels Apr 15, 2026

k8s-ci-robot requested review from varshaprasad96 and vitorfloriano April 15, 2026 19:25

k8s-ci-robot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 15, 2026

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Apr 15, 2026

yosofbadr marked this pull request as ready for review April 16, 2026 04:38

k8s-ci-robot removed do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Apr 16, 2026

k8s-ci-robot requested a review from camilamacedo86 April 16, 2026 04:38

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Apr 16, 2026

camilamacedo86 reviewed Apr 16, 2026

View reviewed changes

Comment thread pkg/plugins/golang/v4/api.go Outdated

camilamacedo86 reviewed Apr 16, 2026

View reviewed changes

Comment thread pkg/plugins/golang/v4/api.go Outdated

camilamacedo86 reviewed Apr 16, 2026

View reviewed changes

Comment thread pkg/cli/init.go Outdated

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 17, 2026

yosofbadr force-pushed the fix/cli-help-text branch from cece673 to e7955f1 Compare April 21, 2026 19:50

camilamacedo86 requested a review from Copilot April 22, 2026 05:32

Copilot started reviewing on behalf of camilamacedo86 April 22, 2026 05:33 View session

Copilot AI reviewed Apr 22, 2026

View reviewed changes

	# Add a second controller for an existing resource
	# Add a controller for an existing resource

		After the files are created, the dependencies will be updated and
		make generate will be run.

-After the files are created, the dependencies will be updated and
-make generate will be run.
+After the files are created, the dependencies will be updated.
+If --make is not set to false and the resource has an API,
+make generate will also be run.

	subcmdMeta.Examples = fmt.Sprintf(` # Create a frigates API with Group: ship, Version: v1beta1 and Kind: Frigate
	subcmdMeta.Examples = fmt.Sprintf(` # Create a frigate API with Group: ship, Version: v1beta1 and Kind: Frigate

		"If set, create the resource without prompting. Default: true. "+
		"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API)")

-		"If set, create the resource without prompting. Default: true. "+
-			"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API)")
+		"If set, create the resource. "+
+			"Use --resource=false to skip resource creation (e.g., when adding a controller for an existing or external API). "+
+			"If not specified, you may be prompted to confirm whether to create the resource")

		"If set, create a namespaced resource. Default: true. "+
		"Use --namespaced=false to create a cluster-scoped resource")

	"If set, create a namespaced resource. Default: true. "+
	"Use --namespaced=false to create a cluster-scoped resource")
	"Resource is namespaced by default; use --namespaced=false to create a cluster-scoped resource")

		Short: "Create a Kubernetes API or webhook",
		Long: fmt.Sprintf(`Create a Kubernetes API or webhook.

		Short: "Create a Kubernetes API",
		Long: `Create a Kubernetes API by writing a Resource definition and/or a Controller.`,

	--resource=false --controller-name frigate-status
	--resource=false --controller=true --controller-name frigate-status

		"If set, create the controller. Default: true. "+
		"Use --controller=false to skip controller creation")

Conversation

yosofbadr commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Files changed

Test plan

Uh oh!

linux-foundation-easycla Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Apr 15, 2026

Uh oh!

k8s-ci-robot commented Apr 15, 2026

Uh oh!

k8s-ci-robot commented Apr 15, 2026

Uh oh!

camilamacedo86 Apr 16, 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!

Uh oh!

Uh oh!

camilamacedo86 commented Apr 16, 2026

Uh oh!

Uh oh!

yosofbadr commented Apr 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Apr 22, 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!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yosofbadr commented Apr 15, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Apr 15, 2026 •

edited

Loading

camilamacedo86 Apr 16, 2026 •

edited

Loading

camilamacedo86 Apr 22, 2026 •

edited

Loading