diff --git a/conventions/cli.md b/conventions/cli.md index 9f0acb10c8..8b39ab76db 100644 --- a/conventions/cli.md +++ b/conventions/cli.md @@ -1,11 +1,13 @@ ## `kn` User Interface Principles -This document describes the conventions that are used for all `kn` commands and options. -It is normative in the sense that any new feature that introduces or changes user-facing commands or options needs to adhere to the given principles. - -Also, the given rules apply to plugins as well. -Especially any plugin that wants to be promoted to the [knative/client-contrib](https://github.com/knative/client-contrib) plugin repository has to adhere to these rules. +This document describes the conventions that are used for all `kn` commands and +options. It is normative in the sense that any new feature that introduces or +changes user-facing commands or options needs to adhere to the given principles. +Also, the given rules apply to plugins as well. Especially any plugin that wants +to be promoted to the +[knative/client-contrib](https://github.com/knative/client-contrib) plugin +repository has to adhere to these rules. ### Command Structure @@ -15,84 +17,104 @@ The general format for kn and plugin commands is kn [ ...] [ ` [1](#foot-1), where [](#noun) is often the name of a resource (e.g. `service`) but can also refer to other concepts (e.g. `plugin` or `config`). -This first noun forms a command group for all the operations you might want to do with that kind -of resource. -Sometimes there can be deeper hierarchies with multiple nouns (`kn .... `) when it makes sense to structure complex concepts. -A good example is `kn source ` which is used like in `kn source ping create`. +So, commands are generally of the form `kn ` +[1](#foot-1), where [](#noun) is often the name of a resource +(e.g. `service`) but can also refer to other concepts (e.g. `plugin` or +`config`). This first noun forms a command group for all the operations you +might want to do with that kind of resource. Sometimes there can be deeper +hierarchies with multiple nouns (`kn .... `) when it +makes sense to structure complex concepts. A good example is +`kn source ` which is used like in `kn source ping create`. -`kn` commands take only positional arguments that are used as [identifiers](#identifier). -This identifier is often the name of a resource which identifies the resource uniquely for the current or given namespace. +`kn` commands take only positional arguments that are used as +[identifiers](#identifier). This identifier is often the name of a resource +which identifies the resource uniquely for the current or given namespace. -Top-level commands concerning the operation of `kn` itself, like `help` and `version` are also okay. +Top-level commands concerning the operation of `kn` itself, like `help` and +`version` are also okay. ### Noun -For resource-related commands, the kind itself used as a command in singular and lowercase form. For example, `service` for -`serving.knative.dev/service` or `trigger` for `eventing.knative.dev/trigger` are the commands for managing these resources respectively +For resource-related commands, the kind itself used as a command in singular and +lowercase form. For example, `service` for `serving.knative.dev/service` or +`trigger` for `eventing.knative.dev/trigger` are the commands for managing these +resources respectively ### Verb -For CRUD (create-retrieve-update-delete) operation the following verbs have to be used: +For CRUD (create-retrieve-update-delete) operation the following verbs have to +be used: -- `describe` prints detailed information about a single resource that can contain data of dependent objects, too. +- `describe` prints detailed information about a single resource that can + contain data of dependent objects, too. - `list` prints summary information about all resources of a type. - `create` creates a resource. - `update` updates a resource. - `delete` deletes a resource. -For a given resource, create and update should use the same arguments as much as possible and where it makes sense. +For a given resource, create and update should use the same arguments as much as +possible and where it makes sense. -Other domain-specific verbs are possible on a case-by-case basis for operations that go beyond basic CRUD operations. +Other domain-specific verbs are possible on a case-by-case basis for operations +that go beyond basic CRUD operations. ### Identifier -For the `CRUD` operations `describe`, `create`, `update`, `delete` the identifier is the resource's name and is required as a positional argument after the commands. -For example it is the last argument that does not start with a flag prefix `-` or `--`. -`list` operations can use a resource name to filter on the resource. +For the `CRUD` operations `describe`, `create`, `update`, `delete` the +identifier is the resource's name and is required as a positional argument after +the commands. For example it is the last argument that does not start with a +flag prefix `-` or `--`. `list` operations can use a resource name to filter on +the resource. Other identifiers can be plugin names or other entities' identifiers. -For bulk operations also multiple identifiers can be provided. -For example, a `delete` operation could use multiple resource names that should be deleted. +For bulk operations also multiple identifiers can be provided. For example, a +`delete` operation could use multiple resource names that should be deleted. ```bash kn service create foo --image gcr.io/things/stuff:tag ``` -In this case, `foo` is positional, and provides the name of the service to create. +In this case, `foo` is positional, and provides the name of the service to +create. ### Flags -Flags are used for specifying the input for `kn` commands and can have different characteristics: +Flags are used for specifying the input for `kn` commands and can have different +characteristics: -* They can be _mandatory_ or _optional_ -* Optional flags can have _default values_ -* Flag values can be _scalars_, _binary_, _lists_ or _maps_ (see below for details) -* Flags always have a long-form (starting with a double `--`) but can also have a shortcut (beginning with a single `-`) -* Every flag has a help message attached -* Flags can be specific to a command or can be globally applicable +- They can be _mandatory_ or _optional_ +- Optional flags can have _default values_ +- Flag values can be _scalars_, _binary_, _lists_ or _maps_ (see below for + details) +- Flags always have a long-form (starting with a double `--`) but can also have + a shortcut (beginning with a single `-`) +- Every flag has a help message attached +- Flags can be specific to a command or can be globally applicable When adding new flags, the following recommendations should be considered: -* Never add a global flag except for very good reasons -* Group related flags together by using a common prefix, like `--label-revision` or `--label-service` so that they appear together in the help message (which is sorted alphabetically) -* Don't add a short form without former discussions -* Choose a name for the flag that is the same or close to the naming used in Knative serving itself like the corresponding CRD field or annotation name. +- Never add a global flag except for very good reasons +- Group related flags together by using a common prefix, like `--label-revision` + or `--label-service` so that they appear together in the help message (which + is sorted alphabetically) +- Don't add a short form without former discussions +- Choose a name for the flag that is the same or close to the naming used in + Knative serving itself like the corresponding CRD field or annotation name. -As mentioned above, flag values can be of different types. -The rules of how these values are modelled on the command line are given below. +As mentioned above, flag values can be of different types. The rules of how +these values are modelled on the command line are given below. #### Scalar -A scalar option is one which just takes a single value. -This value can be a string or a number. -Such an option is allowed to be given only once. -If given multiple times, an error should be thrown. +A scalar option is one which just takes a single value. This value can be a +string or a number. Such an option is allowed to be given only once. If given +multiple times, an error should be thrown. -A scalar flag's value can have an inner structure, too. -For example `--sink svc:myservice` uses a prefix `svc:` to indicate the targeted sink is a Knative Service. - A colon (`:`) should be used as separators if values have a structure. +A scalar flag's value can have an inner structure, too. For example +`--sink svc:myservice` uses a prefix `svc:` to indicate the targeted sink is a +Knative Service. A colon (`:`) should be used as separators if values have a +structure. Example: @@ -103,8 +125,9 @@ kn service create myservice --image docker.io/myuser/myimage #### Binary -Binary flags come in pairs and don't carry any value. -The flag representing the `true` value is just the flag name without a value (e.g. `--wait`) whereas the flag for a `false` value is this name with a `no-` prefix (e.g. `--no-wait`) +Binary flags come in pairs and don't carry any value. The flag representing the +`true` value is just the flag name without a value (e.g. `--wait`) whereas the +flag for a `false` value is this name with a `no-` prefix (e.g. `--no-wait`) Example: @@ -116,16 +139,20 @@ kn service create myservice --wait .... kn service create myservice --no-wait ... ``` -Such a binary option can be provided only once. Otherwise, an error has to be thrown. +Such a binary option can be provided only once. Otherwise, an error has to be +thrown. #### List List flag values can be provided in two flavours: -* Within a single flag value as comma-separated list of key-value pairs (e.g. `--resource pod:v1,job:batch/v1`) -* By providing the same option multiple times (e.g. `--resource pod:v1 --resource job:batch/v1`) +- Within a single flag value as comma-separated list of key-value pairs (e.g. + `--resource pod:v1,job:batch/v1`) +- By providing the same option multiple times (e.g. + `--resource pod:v1 --resource job:batch/v1`) -The value itself can carry a structure where colons separate the parts (`:`), like in the examples above. +The value itself can carry a structure where colons separate the parts (`:`), +like in the examples above. Example: @@ -139,14 +166,20 @@ kn source apiserver create mysrc --resource pod:v1,job:batch/v1 --sink svc:mysvc #### Maps -* Within a single flag value as comma separated list of key-value pairs (e.g. `--env USER=bla,PASSWORD=blub`) -* By providing the same option multiple times (e.g. `--env USER=bla --env PASSWORD=blub`) +- Within a single flag value as comma separated list of key-value pairs (e.g. + `--env USER=bla,PASSWORD=blub`) +- By providing the same option multiple times (e.g. + `--env USER=bla --env PASSWORD=blub`) -For update operations, to _unset_ a value, the key has a dash suffix (`-`) and no value part. For example, to _remove_ an environment variable named `USER` from a service "hello-world". +For update operations, to _unset_ a value, the key has a dash suffix (`-`) and +no value part. For example, to _remove_ an environment variable named `USER` +from a service "hello-world". -If the same key is given multiple times on the command line, the latter definition overwrites the previous one. +If the same key is given multiple times on the command line, the latter +definition overwrites the previous one. Example: + ``` # Create a Service "hello-world" that sets USER and PASSWORD environment variables kn service create hello-world --env USER=bla --env PASSWORD=blub @@ -163,19 +196,23 @@ kn service update hello-world --env USER-,HOME=/root # Same as above, but the last HOME "/home" flag overwrites the previous one kn service update hello-world --env HOME=/root --env USER- --env HOME=/home ``` + ### Shared flags -Certain functionality is the same across command groups. -For example, specifying resource requests and limits via flags can be done when managing services but also for sources. -Those common functionalities should share the same conventions, syntax. +Certain functionality is the same across command groups. For example, specifying +resource requests and limits via flags can be done when managing services but +also for sources. Those common functionalities should share the same +conventions, syntax. Area to which this applies: -* Resource limits -* Output formats, i.e. the data formats supported by the `--output` option (which is reused from k8s' _cli-runtime_) -* Sinks -* .... +- Resource limits +- Output formats, i.e. the data formats supported by the `--output` option + (which is reused from k8s' _cli-runtime_) +- Sinks +- .... _this section needs to be completed with the concrete specifications. tbd_ -1: Note that this differs from the `kubectl` model where this order is vice versa (`kubectl `) +1: Note that this differs from the `kubectl` model where +this order is vice versa (`kubectl `)