# CLI Descriptions

> Standards for CLI command and flag descriptions in Kubebuilder. Use when writing or reviewing CLI flags, commands, or help text.

- Skill: `kubernetes-sigs/cli-descriptions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kubernetes-sigs/cli-descriptions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kubernetes-sigs/cli-descriptions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: kubernetes-sigs (https://skillmd.com/u/kubernetes-sigs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kubernetes-sigs/cli-descriptions

---


# 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:

```go
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](references/REFERENCE.md) for technical references and industry standards that inform these guidelines.