knative
/
client
mirror of https://github.com/knative/client.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[master] Format markdown (#833) 

Produced via:
  `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)`
/assign maximilien rhuss
/cc maximilien rhuss
This commit is contained in:
Matt Moore 2020-05-11 17:22:47 -07:00 committed by GitHub
parent e05c33447e
commit 9bbce80ffa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 100 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
conventions/cli.md
View File

@ -1,11 +1,13 @@
## `kn` User Interface Principles ## `kn` User Interface Principles
This document describes the conventions that are used for all `kn` commands and options. This document describes the conventions that are used for all `kn` commands and
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. 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.
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 ### Command Structure
@ -15,84 +17,104 @@ The general format for kn and plugin commands is
kn <noun> [<noun2> ...] <verb> [<id> <id2] [--opt val1 --opt2 --opt3 ...] kn <noun> [<noun2> ...] <verb> [<id> <id2] [--opt val1 --opt2 --opt3 ...]
``` ```
So, commands are generally of the form `kn <noun> <verb>` <sup>[1](#foot-1)</sup>, where [<noun>](#noun) is often the name of a resource (e.g. `service`) but can also refer to other concepts (e.g. `plugin` or `config`). So, commands are generally of the form `kn <noun> <verb>`
This first noun forms a command group for all the operations you might want to do with that kind <sup>[1](#foot-1)</sup>, where [<noun>](#noun) is often the name of a resource
of resource. (e.g. `service`) but can also refer to other concepts (e.g. `plugin` or
Sometimes there can be deeper hierarchies with multiple nouns (`kn <noun-1> <noun-2> .... <verb>`) when it makes sense to structure complex concepts. `config`). This first noun forms a command group for all the operations you
A good example is `kn source <source-type> <verb>` which is used like in `kn source ping create`. might want to do with that kind of resource. Sometimes there can be deeper
hierarchies with multiple nouns (`kn <noun-1> <noun-2> .... <verb>`) when it
makes sense to structure complex concepts. A good example is
`kn source <source-type> <verb>` which is used like in `kn source ping create`.
`kn` commands take only positional arguments that are used as [identifiers](#identifier). `kn` commands take only positional arguments that are used as
This identifier is often the name of a resource which identifies the resource uniquely for the current or given namespace. [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 ### Noun
For resource-related commands, the kind itself used as a command in singular and lowercase form. For example, `service` for For resource-related commands, the kind itself used as a command in singular and
`serving.knative.dev/service` or `trigger` for `eventing.knative.dev/trigger` are the commands for managing these resources respectively 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 ### 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. - `list` prints summary information about all resources of a type.
- `create` creates a resource. - `create` creates a resource.
- `update` updates a resource. - `update` updates a resource.
- `delete` deletes 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 ### 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 the `CRUD` operations `describe`, `create`, `update`, `delete` the
For example it is the last argument that does not start with a flag prefix `-` or `--`. identifier is the resource's name and is required as a positional argument after
`list` operations can use a resource name to filter on the resource. 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. Other identifiers can be plugin names or other entities' identifiers.
For bulk operations also multiple identifiers can be provided. For bulk operations also multiple identifiers can be provided. For example, a
For example, a `delete` operation could use multiple resource names that should be deleted. `delete` operation could use multiple resource names that should be deleted.
```bash ```bash
kn service create foo --image gcr.io/things/stuff:tag 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
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_ - They can be _mandatory_ or _optional_
* Optional flags can have _default values_ - Optional flags can have _default values_
* Flag values can be _scalars_, _binary_, _lists_ or _maps_ (see below for details) - Flag values can be _scalars_, _binary_, _lists_ or _maps_ (see below for
* Flags always have a long-form (starting with a double `--`) but can also have a shortcut (beginning with a single `-`) details)
* Every flag has a help message attached - Flags always have a long-form (starting with a double `--`) but can also have
* Flags can be specific to a command or can be globally applicable 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: When adding new flags, the following recommendations should be considered:
* Never add a global flag except for very good reasons - 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) - Group related flags together by using a common prefix, like `--label-revision`
* Don't add a short form without former discussions or `--label-service` so that they appear together in the help message (which
* 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. 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. As mentioned above, flag values can be of different types. The rules of how
The rules of how these values are modelled on the command line are given below. these values are modelled on the command line are given below.
#### Scalar #### Scalar
A scalar option is one which just takes a single value. A scalar option is one which just takes a single value. This value can be a
This value can be a string or a number. string or a number. Such an option is allowed to be given only once. If given
Such an option is allowed to be given only once. multiple times, an error should be thrown.
If given multiple times, an error should be thrown.
A scalar flag's value can have an inner structure, too. A scalar flag's value can have an inner structure, too. For example
For example `--sink svc:myservice` uses a prefix `svc:` to indicate the targeted sink is a Knative Service. `--sink svc:myservice` uses a prefix `svc:` to indicate the targeted sink is a
A colon (`:`) should be used as separators if values have a structure. Knative Service. A colon (`:`) should be used as separators if values have a
structure.
Example: Example:
@ -103,8 +125,9 @@ kn service create myservice --image docker.io/myuser/myimage
#### Binary #### Binary
Binary flags come in pairs and don't carry any value. Binary flags come in pairs and don't carry any value. The flag representing the
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`) `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: Example:
@ -116,16 +139,20 @@ kn service create myservice --wait ....
kn service create myservice --no-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
List flag values can be provided in two flavours: 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`) - Within a single flag value as comma-separated list of key-value pairs (e.g.
* By providing the same option multiple times (e.g. `--resource pod:v1 --resource job:batch/v1`) `--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: Example:
@ -139,14 +166,20 @@ kn source apiserver create mysrc --resource pod:v1,job:batch/v1 --sink svc:mysvc
#### Maps #### Maps
* Within a single flag value as comma separated list of key-value pairs (e.g. `--env USER=bla,PASSWORD=blub`) - Within a single flag value as comma separated list of key-value pairs (e.g.
* By providing the same option multiple times (e.g. `--env USER=bla --env PASSWORD=blub`) `--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: Example:
``` ```
# Create a Service "hello-world" that sets USER and PASSWORD environment variables # Create a Service "hello-world" that sets USER and PASSWORD environment variables
kn service create hello-world --env USER=bla --env PASSWORD=blub 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 # 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 kn service update hello-world --env HOME=/root --env USER- --env HOME=/home
``` ```
### Shared flags ### Shared flags
Certain functionality is the same across command groups. Certain functionality is the same across command groups. For example, specifying
For example, specifying resource requests and limits via flags can be done when managing services but also for sources. resource requests and limits via flags can be done when managing services but
Those common functionalities should share the same conventions, syntax. also for sources. Those common functionalities should share the same
conventions, syntax.
Area to which this applies: Area to which this applies:
* Resource limits - Resource limits
* Output formats, i.e. the data formats supported by the `--output` option (which is reused from k8s' _cli-runtime_) - Output formats, i.e. the data formats supported by the `--output` option
* Sinks (which is reused from k8s' _cli-runtime_)
* .... - Sinks
- ....
_this section needs to be completed with the concrete specifications. tbd_ _this section needs to be completed with the concrete specifications. tbd_
<a name="foot-1">1</a>: Note that this differs from the `kubectl` model where this order is vice versa (`kubectl <verb> <noun>`) <a name="foot-1">1</a>: Note that this differs from the `kubectl` model where
this order is vice versa (`kubectl <verb> <noun>`)