Skip to content

fix: improve CLI flag descriptions and help text for create api command #5628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yosofbadr wants to merge 1 commit into
base: master
Choose a base branch
from
+27 −14
Open

fix: improve CLI flag descriptions and help text for create api command #5628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions pkg/cli/api.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ const apiErrorMsg = "failed to create API"
func (c CLI) newCreateAPICmd() *cobra.Command {
cmd := &cobra.Command{
Use: "api",
Short: "Scaffold a Kubernetes API",
Long: `Scaffold a Kubernetes API.`,
Short: "Create a Kubernetes API",
Long: `Create a Kubernetes API by writing a Resource definition and/or a Controller.`,
Comment on lines +32 to +33
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
RunE: errCmdFunc(
fmt.Errorf("api subcommand requires an existing project"),
),
Expand Down
4 changes: 2 additions & 2 deletions pkg/cli/create.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ func (c CLI) newCreateCmd() *cobra.Command {
return &cobra.Command{
Use: "create",
SuggestFor: []string{"new"},
Short: "Scaffold a Kubernetes API or webhook",
Long: fmt.Sprintf(`Scaffold a Kubernetes API or webhook.
Short: "Create a Kubernetes API or webhook",
Long: fmt.Sprintf(`Create a Kubernetes API or webhook.
Comment on lines +31 to +32
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@camilamacedo86 camilamacedo86 Apr 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Available plugins that support 'create' subcommands:

Expand Down
33 changes: 23 additions & 10 deletions pkg/plugins/golang/v4/api.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,19 +59,29 @@ type createAPISubcommand struct {
}

func (p *createAPISubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
subcmdMeta.Description = `Scaffold a Kubernetes API by writing a Resource definition and/or a Controller.
subcmdMeta.Description = `Create a Kubernetes API by writing a Resource definition and/or a Controller.

If information about whether the resource and controller should be scaffolded
If information about whether the resource and controller should be created
was not explicitly provided, it will prompt the user if they should be.

After the scaffold is written, the dependencies will be updated and
After the files are created, the dependencies will be updated and
make generate will be run.
Comment on lines +67 to 68
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
`
subcmdMeta.Examples = fmt.Sprintf(` # Create a frigates API with Group: ship, Version: v1beta1 and Kind: Frigate
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
%[1]s create api --group ship --version v1beta1 --kind Frigate

# 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
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

# Scaffold a controller for an external API (e.g., cert-manager)
%[1]s create api --group certmanager --version v1 --kind Certificate \
--resource=false --controller \
--external-api-path github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
--external-api-domain cert-manager.io \
--external-api-module github.com/cert-manager/[email protected]

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

# Edit the Controller
Expand All @@ -93,25 +103,28 @@ make generate will be run.

func (p *createAPISubcommand) BindFlags(fs *pflag.FlagSet) {
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")
Comment on lines 105 to +107
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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 uses AI. Check for mistakes.

fs.BoolVar(&p.force, "force", false,
"If set, attempt to create resource even if it already exists")
"If set, attempt to create the resource even if it already exists")

p.options = &goPlugin.Options{}

fs.StringVar(&p.options.Plural, "plural", "",
"Resource irregular plural form (e.g., 'people' for 'Person'); auto-detected if not provided")

fs.BoolVar(&p.options.DoAPI, "resource", true,
"Generate the resource without prompting the user (enabled by default; use --resource=false to disable)")
"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)")
Comment on lines +118 to +119
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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 uses AI. Check for mistakes.
p.resourceFlag = fs.Lookup("resource")
fs.BoolVar(&p.options.Namespaced, "namespaced", true,
"Resource is namespaced by default; 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")
Comment on lines +122 to +123
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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 uses AI. Check for mistakes.

fs.BoolVar(&p.options.DoController, "controller", true,
"Prompt whether to generate the controller by default; "+
"use --controller=true or --controller=false to skip the prompt")
"If set, create the controller. Default: true. "+
"Use --controller=false to skip controller creation")
Comment on lines +126 to +127
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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")

Copilot uses AI. Check for mistakes.
p.controllerFlag = fs.Lookup("controller")

fs.StringVar(&p.options.ControllerName, "controller-name", "",
Expand Down
Loading