Skip to content

✨ feat(cli): Show hint message when file completion not applicable to subcommand #5587

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

Draft
vitorfloriano wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

✨ feat(cli): Show hint message when file completion not applicable to subcommand #5587

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
14 changes: 14 additions & 0 deletions internal/cli/alpha/generate.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,20 @@ If no output directory is provided, the current working directory will be cleane
},
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
scaffoldCmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user types a partial token before TAB, this will return no completions + ShellCompDirectiveNoFileComp and show nothing. Consider appending ActiveHelp whenever len(args) == 0 (or when the token isn't a flag) so guidance is still shown.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || toComplete[0] != '-') {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
Copy link
Copy Markdown
Contributor Author

@vitorfloriano vitorfloriano Apr 7, 2026

Choose a reason for hiding this comment

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

Or we could do something like:

Suggested change
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
completions = cobra.AppendActiveHelp(completions, "Type '--help' to get help. Type '--' and press TAB to list flags.")

Or:

Suggested change
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags. Type '--help' to show help.")

Copy link
Copy Markdown
Member

@camilamacedo86 camilamacedo86 Apr 7, 2026

Choose a reason for hiding this comment

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

I think, if possible we need to check how to solve in the CLI without need to implement each command.

Copy link
Copy Markdown
Contributor Author

@vitorfloriano vitorfloriano Apr 7, 2026

Choose a reason for hiding this comment

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

I think, if possible we need to check how to solve in the CLI without need to implement each command.

ValidArgsFunction is a field in the cobra.Command struct. It's like Use, Run, PreRunE and alike. It needs to be implemented in each command.

There may be way to work around this and make it global, but I don't think that's very idiomatic and will possibly have side-effects.

}
return completions, cobra.ShellCompDirectiveNoFileComp
}

scaffoldCmd.Flags().StringVar(&opts.InputDir, "input-dir", "",
"Path to the directory containing the PROJECT file. "+
"Defaults to the current working directory. WARNING: delete existing files (except .git and PROJECT).")
Expand Down
14 changes: 14 additions & 0 deletions internal/cli/alpha/update.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,20 @@ Defaults:
},
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
updateCmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user starts typing a token before pressing TAB, this returns no completions + ShellCompDirectiveNoFileComp, so no hint is displayed. Consider appending ActiveHelp whenever len(args) == 0 (or when the token isn't a flag) so users still get guidance.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || toComplete[0] != '-') {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}

updateCmd.Flags().StringVar(&opts.FromVersion, "from-version", "",
"binary release version to upgrade from. Should match the version used to init the project and be "+
"a valid release version, e.g., v4.6.0. If not set, it defaults to the version specified in the PROJECT file.")
Expand Down
14 changes: 14 additions & 0 deletions pkg/cli/api.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,20 @@ func (c CLI) newCreateAPICmd() *cobra.Command {
),
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
cmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user types any partial token before TAB (e.g. kubebuilder create api x<TAB>), this returns no completions + ShellCompDirectiveNoFileComp, so nothing is shown and the hint is lost. Consider showing the hint whenever len(args) == 0 (or at least when len(args) == 0 and the token isn't a flag) so the UX is consistent.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || toComplete[0] != '-') {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}
Comment on lines +40 to +52
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

This same ValidArgsFunction block (including the literal hint string) is duplicated across multiple commands/files in this PR. To keep behavior and wording consistent over time, consider extracting this into a small helper (e.g. a function that sets the ValidArgsFunction) and/or a shared const for the hint message.

Copilot uses AI. Check for mistakes.

// In case no plugin was resolved, instead of failing the construction of the CLI, fail the execution of
// this subcommand. This allows the use of subcommands that do not require resolved plugins like help.
if len(c.resolvedPlugins) == 0 {
Expand Down
14 changes: 14 additions & 0 deletions pkg/cli/edit.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,20 @@ func (c CLI) newEditCmd() *cobra.Command {
),
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
cmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user types any partial token before TAB, this returns no completions + ShellCompDirectiveNoFileComp, so nothing is shown. Consider showing the hint whenever len(args) == 0 (or when the token isn't a flag) so the UX remains helpful in more cases.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || toComplete[0] != '-') {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}

// In case no plugin was resolved, instead of failing the construction of the CLI, fail the execution of
// this subcommand. This allows the use of subcommands that do not require resolved plugins like help.
if len(c.resolvedPlugins) == 0 {
Expand Down
14 changes: 14 additions & 0 deletions pkg/cli/init.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,20 @@ For further help about a specific plugin, set --plugins.
Run: func(_ *cobra.Command, _ []string) {},
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
cmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user has started typing an argument before pressing TAB, completion will return nothing and the hint won't appear. Consider appending ActiveHelp whenever len(args) == 0 (or when the token isn't a flag) so users still get guidance.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || !strings.HasPrefix(toComplete, "-")) {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}

// Register --project-version on the dynamically created command
// so that it shows up in help and does not cause a parse error.
cmd.Flags().String(projectVersionFlag, c.defaultProjectVersion.String(), "project version")
Expand Down
15 changes: 15 additions & 0 deletions pkg/cli/version.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,5 +33,20 @@ func (c CLI) newVersionCmd() *cobra.Command {
return nil
},
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
cmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user starts typing a token and then presses TAB, this returns no completions + ShellCompDirectiveNoFileComp, so no hint is displayed. Consider showing the hint whenever len(args) == 0 (or when the token isn't a flag) to keep the behavior consistent.

Suggested change
if len(args) == 0 && toComplete == "" {
if len(args) == 0 && (toComplete == "" || toComplete[0] != '-') {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}
Comment on lines +37 to +49
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

PR description lists the subcommands being updated, but version is also modified here. Either include version in the description (if intended) or drop this change to keep the scope aligned with the PR narrative.

Copilot uses AI. Check for mistakes.

return cmd
}
14 changes: 14 additions & 0 deletions pkg/cli/webhook.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,20 @@ func (c CLI) newCreateWebhookCmd() *cobra.Command {
),
}

// Show hint message on how to list flags instead of showing file completion for
// commands that don't take files as arguments
cmd.ValidArgsFunction = func(
_ *cobra.Command,
args []string,
toComplete string,
) ([]cobra.Completion, cobra.ShellCompDirective) {
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
Comment on lines +47 to +48
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

The ActiveHelp hint is only appended when toComplete == "". If the user starts typing an argument before TAB, completion will return nothing and the hint won't show. Consider appending ActiveHelp whenever len(args) == 0 (or when the token isn't a flag) for a more consistent UX.

Suggested change
completions := []cobra.Completion{}
if len(args) == 0 && toComplete == "" {
_ = toComplete
completions := []cobra.Completion{}
if len(args) == 0 {

Copilot uses AI. Check for mistakes.
completions = cobra.AppendActiveHelp(completions, "Type '--' and press TAB to list flags")
}
return completions, cobra.ShellCompDirectiveNoFileComp
}

// In case no plugin was resolved, instead of failing the construction of the CLI, fail the execution of
// this subcommand. This allows the use of subcommands that do not require resolved plugins like help.
if len(c.resolvedPlugins) == 0 {
Expand Down