cli-descriptions

name	cli-descriptions
description	Standards for CLI command and flag descriptions in Kubebuilder. Use when writing or reviewing CLI flags, commands, or help text.
license	Apache-2.0
metadata	{"author":"The Kubernetes Authors"}

CLI Description Standards for Kubebuilder

Use this skill to write, review, or normalize Kubebuilder CLI command descriptions, flag help text, and examples.

Workflow

1. Identify the CLI element:
   • boolean flag
   • value flag
   • command short description
   • command long description
   • examples/help text
2. Apply the matching standard below.
3. Rewrite the text to match the standard.
4. If reviewing, explain the issue briefly and propose the corrected wording.

Core principles

• Prefer clarity over brevity.
• Use consistent patterns across similar flags and commands.
• Include examples, defaults, or fallback behavior when useful.
• Tell users what happens when they use the flag.

Boolean flags

Default false (opt-in behavior)

Use this pattern:

If set, <what happens>

Examples:

• If set, enable multigroup layout (organize APIs by group)
• If set, skip Go version check
• If set, attempt to create resource even if it already exists

Default true (opt-out behavior)

When a boolean flag defaults to true, describe the behavior and how to disable it:

<what happens by default>; use --flag=false to <opposite behavior>

Or for flags with more context:

<what happens> (enabled by default; use --flag=false to disable)

Examples:

• Run 'make generate' after generating files (enabled by default; use --make=false to disable)
• Run 'make manifests' after generating files (enabled by default; use --manifests=false to disable)
• Resource is namespaced by default; use --namespaced=false to create a cluster-scoped resource
• Generate the resource without prompting the user (enabled by default; use --resource=false to disable)
• Download dependencies after scaffolding (enabled by default; use --fetch-deps=false to disable)

Tri-state (enable/disable/preserve)

When a boolean flag preserves existing values if not provided, and supports both enabling and disabling:

Enable or disable <what>; use --flag=false to disable

Examples:

• Enable or disable multigroup layout (organize APIs by group); use --multigroup=false to disable
• Enable or disable namespace-scoped deployment (default: cluster-scoped); use --namespaced=false to disable

Prompting flags

When a flag controls prompting behavior (prompts by default, but accepts explicit true/false to skip the prompt):

Prompt whether to <action> by default; use --flag=true or --flag=false to skip the prompt

Examples:

• Prompt whether to generate the controller by default; use --controller=true or --controller=false to skip the prompt

Value flags

Use these patterns:

With an example:

<what> (e.g., <example>)

With a default:

<what> (e.g., <example>). Defaults to <default> if unset

With auto-detection:

<what> (e.g., <example>); auto-detected <method> if not provided

Examples:

• Go module name (e.g., github.com/user/repo); auto-detected from current directory if not provided
• License header to use for boilerplate (e.g., apache2, none). Defaults to apache2 if unset
• Project version (e.g., 3). Defaults to CLI version if unset
• Domain for your APIs (e.g., example.org creates crew.example.org for API groups)

Optional value flags

When a flag is optional and modifies behavior, use:

[Optional] <what>. <additional context if useful> (e.g., <example>)

Examples:

• [Optional] Container command to use for image initialization (e.g., --image-container-command="memcached,--memory-limit=64,modern,-o,-v")
• [Optional] Container port used by the container image (e.g., --image-container-port="11211")

Path flags

Use:

Path to <what>; <behavior> (e.g., <example>)

Example:

• Path to custom license file; content copied to hack/boilerplate.go.txt (overrides --license)

List flags

For comma-separated lists or arrays:

Comma-separated list of <what> (e.g., --flag value1,value2)

Example:

• Comma-separated list of spoke versions to be added to the conversion webhook (e.g., --spoke v1,v2)

Deprecated flags

For deprecated flags that will be removed in future versions:

[DEPRECATED] If set, <what it does>. This option will be removed in future versions

Example:

• [DEPRECATED] If set, uses the old behavior for <feature>. This option will be removed in future versions

Command short descriptions

Rules:

• Start with a capital letter.
• Use a brief phrase or sentence.
• Do not end with a period.
• Prefer imperative wording.

Examples:

• Initialize a new project
• Scaffold a Kubernetes API
• Scaffold a Kubernetes API or webhook

Command long descriptions

Long descriptions should:

• explain what the command does
• mention generated files or directories when relevant
• separate required vs optional/configuration flags when helpful
• use full sentences and punctuation
• include behavioral notes when useful

Use this structure when it fits:

Initialize a new project including the following files:
  - a "go.mod" with project dependencies
  - a "PROJECT" file that stores project configuration
  - a "Makefile" with useful make targets

Required flags:
  --domain: Domain for your APIs (e.g., example.org creates crew.example.org for API groups)

Configuration flags:
  --repo: Go module name (e.g., github.com/user/repo); auto-detected from current directory if not provided

Note: Layout settings can be changed later with 'kubebuilder edit'.

Command examples

Examples should:

• be realistic and valid
• progress from simple to complex
• explain non-obvious cases
• use the command name variable when writing Go examples

Example:

subcmdMeta.Examples = fmt.Sprintf(`  # Initialize a new project
  %[1]s init --domain example.org

  # Initialize with multigroup layout
  %[1]s init --domain example.org --multigroup

  # Initialize with all options combined
  %[1]s init --plugins go/v4,autoupdate/v1-alpha --domain example.org --multigroup --namespaced
`, cliMeta.CommandName)

Common Kubebuilder flag wording

Use these standard descriptions when applicable:

• --domain: Domain for your APIs (e.g., example.org creates crew.example.org for API groups)
• --repo: Go module name (e.g., github.com/user/repo); auto-detected from current directory if not provided
• --plugins: Comma-separated list of plugin keys to use (e.g., go/v4, helm/v2-alpha). Defaults to the built-in go/v4 bundle if unset
• --multigroup:
  • In init: If set, enable multigroup layout (organize APIs by group)
  • In edit: Enable or disable multigroup layout (organize APIs by group); use --multigroup=false to disable
• --skip-go-version-check:
  • When default is false: If set, skip Go version check
  • When default is true: Skip the Go version check (enabled by default; use --skip-go-version-check=false to enforce)
• --force: If set, attempt to create resource even if it already exists (or If set, regenerate all files except Chart.yaml for helm plugins)
• --license:
  • In init: License header to use for boilerplate (e.g., apache2, none). Defaults to apache2 if unset
  • In edit: License header to use for boilerplate (e.g., apache2, none). If unset, preserves the existing boilerplate
• --owner: Owner name for copyright license headers
• --namespaced:
  • In api: Resource is namespaced by default; use --namespaced=false to create a cluster-scoped resource
  • In edit: Enable or disable namespace-scoped deployment (default: cluster-scoped); use --namespaced=false to disable
• --fetch-deps: Download dependencies after scaffolding (enabled by default; use --fetch-deps=false to disable)
• --make: Run 'make generate' after generating files (enabled by default; use --make=false to disable)
• --manifests: Run 'make manifests' after generating files (enabled by default; use --manifests=false to disable)
• --resource: Generate the resource without prompting the user (enabled by default; use --resource=false to disable)
• --controller: Prompt whether to generate the controller by default; use --controller=true or --controller=false to skip the prompt

Review output pattern

When reviewing, use this format:

• Issue: one short sentence describing what is wrong
• Suggested text: the corrected help text
• Reason: one short sentence tying it back to the standard

Example:

• Issue: Boolean flag description does not describe the behavior when the flag is present.
• Suggested text: If set, enable multigroup layout (organize APIs by group)
• Reason: Boolean flags should follow the If set, ... pattern.

Checklist

• Boolean flags that default to false use If set, ...
• Boolean flags that default to true describe the behavior and how to disable (e.g., "enabled by default; use --flag=false to disable")
• Value flags include examples with (e.g., ...)
• List flags use Comma-separated list of ...
• Deprecated flags are marked with [DEPRECATED]
• Defaults are explicitly stated when they exist with "if unset" (e.g., "Defaults to X if unset")
• Auto-detection or fallback behavior is documented
• Short descriptions are capitalized and do not end with a period
• Long descriptions are complete and organized
• Examples are realistic and valid
• Terminology is consistent across commands and plugins

Notes

• Apply these standards across all Kubebuilder plugins.
• Prefer consistency across the codebase over one-off wording choices.
• When the same flag appears with equivalent semantics across plugins, use identical descriptions. When semantics differ (e.g., --force in create/api/edit, or --license in init/edit), document the per-command variant explicitly.
• Flag descriptions should not end with a period (matches the --help convention used by cobra and the rest of Kubebuilder).
• For multi-line flag descriptions in code, use string concatenation with + and break at natural boundaries (70-80 characters per line).
• When in doubt, choose the wording that is clearest in --help output.
• See references/REFERENCE.md for technical references and industry standards that inform these guidelines.