Propose command standards #2751
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Proposed changes verification passedThis pull request comes with up-to-date documentation and no illegal standard output usages. Find more detailed information in the |
musztardem
reviewed
Nov 28, 2025
|
|
||
| ## Command messaging | ||
|
|
||
| It's not allowed to use the `os.Stdout`/`os.Stderr` and `fmt.Print` functionalities. Instead of that we must use the [out](../../../internal/out/out.go) package that provide centralized control over writers. |
Contributor
There was a problem hiding this comment.
Maybe in this section it would be useful to describe how specific out writers should be used? E.g. explain that out.Debug works only with the hidden --debug flag etc
Contributor
There was a problem hiding this comment.
out.Verbose and out.Debug are almost identical from the code perspective but they serve different purposes
musztardem
reviewed
Nov 28, 2025
|
|
||
| The long one describes what exactly the command is doing. It can be multiline, describing all use-cases. It must start with a huge letter and always end with a period. | ||
|
|
||
| ## Flags |
Contributor
There was a problem hiding this comment.
Do you think it would be worth mentioning in this section about flags that are available in every command? Or maybe adding another section describing Global flags
Contributor
There was a problem hiding this comment.
Another thing: we haven't decide on the approach yet but it would be good to also standarize flags that are used across different commands like --format and --output
anoipm
reviewed
Nov 30, 2025
| explain [flags] # runnable command without argument | ||
| create <name> [flags] # runnable command that receive one required arg and optional flags | ||
| scale <name> <replicas> [flags] # runnable command that can receive two arguments and optional flags | ||
| delete <name\s> # runnable command that receive at least one argument and has no flags |
Contributor
There was a problem hiding this comment.
I prefer something like <name>... or (<name>...). Se also kubectl get --help.
|
|
||
| The command name must be a verb or noun. In most cases, it is recommended to use nouns to define domain-related command groups (like `kyma function`, `kyma app`, or `kyma apirule`) and verbs to define runnable operations around the domain (like `kyma app push`, `kyma function create`, `kyma apirule expose`). This rule is only a suggestion, and it depends on the use case. For example, the `kyma diagnose` command works as a runnable command and command group at the same (`kyma diagnose logs`) time, and because of this, it's not a noun. On the other hand, the `kyma registry config` in another example, where after the noun is another noun (runnable noun), but in this case, the `config` word is shorter than `get-config`. | ||
|
|
||
| After the first word, there must be a description of possible arguments/commands. If the command is a non-runnable command group, then it should contain `<command>`, which means that this command accepts only one argument, and this argument is the command name. If command is runnable then is must describes possible inputs (if allowed) in the following format: `<arg_name>` for single, required argument, `<arg_name/s>` for at least one required argument, `[<arg_name>]` for one optional argument, `[<arg_name/s>]` for optional arguments list of the same type. If the command receives more than one argument type, then it is possible to describe many arguments separated by a space. For example: `scale <name> <replicas>` |
Contributor
There was a problem hiding this comment.
Unification with the previous proposal:
Suggested change
| After the first word, there must be a description of possible arguments/commands. If the command is a non-runnable command group, then it should contain `<command>`, which means that this command accepts only one argument, and this argument is the command name. If command is runnable then is must describes possible inputs (if allowed) in the following format: `<arg_name>` for single, required argument, `<arg_name/s>` for at least one required argument, `[<arg_name>]` for one optional argument, `[<arg_name/s>]` for optional arguments list of the same type. If the command receives more than one argument type, then it is possible to describe many arguments separated by a space. For example: `scale <name> <replicas>` | |
| After the first word, there must be a description of possible arguments/commands. If the command is a non-runnable command group, then it should contain `<command>`, which means that this command accepts only one argument, and this argument is the command name. If command is runnable then is must describes possible inputs (if allowed) in the following format: `<arg_name>` for single, required argument, `(<arg_name>...)` for at least one required argument, `[<arg_name>]` for one optional argument, `[<arg_name>...]` for optional arguments list of the same type. If the command receives more than one argument type, then it is possible to describe many arguments separated by a space. For example: `scale <name> <replicas>` |
| The parents help: | ||
|
|
||
| ```bash | ||
| kyma module --help |
Contributor
There was a problem hiding this comment.
An additional character ($) to distinguish the command from the result.
Suggested change
| kyma module --help | |
| $ kyma module --help |
| The commands help: | ||
|
|
||
| ```bash | ||
| kyma module catalog --help |
Contributor
There was a problem hiding this comment.
Suggested change
| kyma module catalog --help | |
| $ kyma module catalog --help |
| The commands help looks: | ||
|
|
||
| ```bash | ||
| kyma module add --help |
Contributor
There was a problem hiding this comment.
Suggested change
| kyma module add --help | |
| $ kyma module add --help |
| The help will displays: | ||
|
|
||
| ```bash | ||
| kyma module add --help |
Contributor
There was a problem hiding this comment.
Suggested change
| kyma module add --help | |
| $ kyma module add --help |
grego952
reviewed
Dec 1, 2025
|
|
||
| ### Name details | ||
|
|
||
| The command name must be a verb or noun. In most cases, it is recommended to use nouns to define domain-related command groups (like `kyma function`, `kyma app`, or `kyma apirule`) and verbs to define runnable operations around the domain (like `kyma app push`, `kyma function create`, `kyma apirule expose`). This rule is only a suggestion, and it depends on the use case. For example, the `kyma diagnose` command works as a runnable command and command group at the same (`kyma diagnose logs`) time, and because of this, it's not a noun. On the other hand, the `kyma registry config` in another example, where after the noun is another noun (runnable noun), but in this case, the `config` word is shorter than `get-config`. |
Contributor
There was a problem hiding this comment.
Based on this, I assume that a verb or noun is a suggestion, not a must.
Actually, config can be used informally as configure, so it can be treated as a verb.
|
|
||
| After the first word, there must be a description of possible arguments/commands. If the command is a non-runnable command group, then it should contain `<command>`, which means that this command accepts only one argument, and this argument is the command name. If command is runnable then is must describes possible inputs (if allowed) in the following format: `<arg_name>` for single, required argument, `<arg_name/s>` for at least one required argument, `[<arg_name>]` for one optional argument, `[<arg_name/s>]` for optional arguments list of the same type. If the command receives more than one argument type, then it is possible to describe many arguments separated by a space. For example: `scale <name> <replicas>` | ||
|
|
||
| The last element must be optional flags represented by the `[flags]` element. In our case, it must be a part of every command because we add persistent flags for the parent `kyma` command, and these flags will be valid for every sub-command. |
Contributor
There was a problem hiding this comment.
Suggested change
| The last element must be optional flags represented by the `[flags]` element. In our case, it must be a part of every command because we add persistent flags for the parent `kyma` command, and these flags will be valid for every sub-command. | |
| The last element must be optional flags represented by the `[flags]` element. In our case, it must be a part of every command because we add persistent flags for the parent `kyma` command, and these flags are valid for every sub-command. |
|
|
||
| ## Descriptions | ||
|
|
||
| There are two types of description under the `cobra.Command{}.Short` and the `cobra.Command{}.Long` fields. The first one represents a shorter description that will be shown when running parent commands help, and the second one when running the current command. |
Contributor
There was a problem hiding this comment.
Suggested change
| There are two types of description under the `cobra.Command{}.Short` and the `cobra.Command{}.Long` fields. The first one represents a shorter description that will be shown when running parent commands help, and the second one when running the current command. | |
| There are two types of description under the `cobra.Command{}.Short` and the `cobra.Command{}.Long` fields. The first one represents a shorter description that is displayed when running parent commands help, and the second one is displayed when running the current command. |
|
|
||
| ### Description details | ||
|
|
||
| The short desc should help users choose the right sub-command in the context of the domain they are in. This description must start with a huge letter and end without a period. |
Contributor
There was a problem hiding this comment.
Suggested change
| The short desc should help users choose the right sub-command in the context of the domain they are in. This description must start with a huge letter and end without a period. | |
| The short desc helps users choose the right sub-command in the context of the domain they are in. This description must start with a capital letter and end without a period. |
|
|
||
| The short desc should help users choose the right sub-command in the context of the domain they are in. This description must start with a huge letter and end without a period. | ||
|
|
||
| The long one describes what exactly the command is doing. It can be multiline, describing all use-cases. It must start with a huge letter and always end with a period. |
Contributor
There was a problem hiding this comment.
Suggested change
| The long one describes what exactly the command is doing. It can be multiline, describing all use-cases. It must start with a huge letter and always end with a period. | |
| The longer one describes exactly what the command is doing. It can be multiline, describing all use-cases. It must start with a capital letter and always end with a period. |
|
|
||
| Every line of the examples must start with double spaces to display them correctly in the terminal. | ||
|
|
||
| All examples for one command must be separated with an empty line and have their own description starting from the `#` symbol. If the example description is longer than one line, then the first line should start with the `##` prefix, and then every next line should start with `#` and two spaces after. |
Contributor
There was a problem hiding this comment.
Suggested change
| All examples for one command must be separated with an empty line and have their own description starting from the `#` symbol. If the example description is longer than one line, then the first line should start with the `##` prefix, and then every next line should start with `#` and two spaces after. | |
| All examples for a single command must be separated by an empty line and include their own description, starting with the `#` symbol. If the example description is longer than one line, then the first line should start with the `##` prefix, and then every next line should start with `#` and two spaces after. |
|
|
||
| All examples for one command must be separated with an empty line and have their own description starting from the `#` symbol. If the example description is longer than one line, then the first line should start with the `##` prefix, and then every next line should start with `#` and two spaces after. | ||
|
|
||
| Examples should reflect real use cases, so if possible, they should use real data as arguments and flags if possible. If not, then use fiction one representing real data, like `my-module`, `my-resource`, `my-something`. |
Contributor
There was a problem hiding this comment.
Suggested change
| Examples should reflect real use cases, so if possible, they should use real data as arguments and flags if possible. If not, then use fiction one representing real data, like `my-module`, `my-resource`, `my-something`. | |
| Examples should reflect real use cases, so, if possible, they should use real data as arguments and flags. If not, then use fiction one representing real data, like `my-module`, `my-resource`, `my-something`. |
| } | ||
| ``` | ||
|
|
||
| ## Errors&Hints |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Errors&Hints | |
| ## Errors and Hints |
|
|
||
| ## Errors&Hints | ||
|
|
||
| Errors were proposed in the [ADR 001](001-error-output-format.md) proposal and implemented quite after that. This functionality allows users to understand what is going on on three levels of abstraction. The general message called `Error` should contain the last, user-understandable operation that fails. The second thing is `Error Details` that can contain an internal error message generated from the library or called server. The `Hints` section is something that should help users figure out how the problem can be fixed. Every hint should be in one of two formats: |
Contributor
There was a problem hiding this comment.
Suggested change
| Errors were proposed in the [ADR 001](001-error-output-format.md) proposal and implemented quite after that. This functionality allows users to understand what is going on on three levels of abstraction. The general message called `Error` should contain the last, user-understandable operation that fails. The second thing is `Error Details` that can contain an internal error message generated from the library or called server. The `Hints` section is something that should help users figure out how the problem can be fixed. Every hint should be in one of two formats: | |
| Errors were proposed in the [ADR 001](001-error-output-format.md) proposal and implemented quite a while after that. With this functionality, users can understand what is going on at three levels of abstraction. The general message called `Error` should contain the last, user-understandable operation that fails. The second thing is `Error Details`, which contains an internal error message generated by the library or the server. The `Hints` section is designed to help users identify how to fix the problem. Every hint should be in one of two formats: |
| * `to <what>, <do>` - format used to describe possible optional configurations that may be used or misconfigured | ||
| * `make sure <what>` - format used to describe the required configuration user may have misconfigured | ||
|
|
||
| The cli is designed to always return `clierror.Error` instead of pure `error`. Both errors are not compatible with each other, and to avoid user confusion, we should not use the `cobra.Command{}.RunE` and instead of that use the `cobra.Command{}.Run` and check the error manually inside of it: |
Contributor
There was a problem hiding this comment.
Suggested change
| The cli is designed to always return `clierror.Error` instead of pure `error`. Both errors are not compatible with each other, and to avoid user confusion, we should not use the `cobra.Command{}.RunE` and instead of that use the `cobra.Command{}.Run` and check the error manually inside of it: | |
| The CLI is designed to always return `clierror.Error` instead of pure `error`. Both errors are not compatible with each other, and to avoid user confusion, we should not use the `cobra.Command{}.RunE` and instead of that use the `cobra.Command{}.Run` and check the error manually inside of it: |
FilipRudy
reviewed
Dec 2, 2025
|
|
||
| ## Command messaging | ||
|
|
||
| It's not allowed to use the `os.Stdout`/`os.Stderr` and `fmt.Print` functionalities. Instead of that we must use the [out](../../../internal/out/out.go) package that provide centralized control over writers. |
Contributor
There was a problem hiding this comment.
Maybe leave a small explanation why it's not allowed to use both os.Stdout/os.Stderr and fmt.Print functionalities.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Changes proposed in this pull request: