From 8c27978855aa56601494138a194c868d2fbc48ef Mon Sep 17 00:00:00 2001
From: Naomi Seyfer <seyfer@google.com>
Date: Fri, 19 Jul 2019 14:11:31 -0700
Subject: [PATCH] Command conventions doc (#270)

* Command conventions doc copied from https://docs.google.com/document/d/1Or3f51EIrdyuwlJ9IfhQdoe7F7WrjsUPEPa0Ijsv2go/edit#

* Update with comments
---
 conventions/cli.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 conventions/cli.md

diff --git a/conventions/cli.md b/conventions/cli.md
new file mode 100644
index 000000000..db68aa703
--- /dev/null
+++ b/conventions/cli.md
@@ -0,0 +1,71 @@
+# Guidelines for `kn` Commands
+
+Commands are generally of the form `kn <resource> <verb>`; the resource kind
+forms a command group for all the operations you might want to do with that kind
+of resource.
+
+Commands that directly concern more than one resource kind may be categorized
+with one of the relevant resources, or may get their own top-level verb
+(eg. `connect`).
+
+Top-level commands concerning the operation of `kn` itself, like `help` and
+`version` are also okay.
+
+## Resource
+
+The <group>.knative.dev Kind, singluar and lowercase. For example, `service` for
+`serving.knative.dev/service` or `trigger` for `eventing.knative.dev/trigger`.
+
+## Verb
+
+If the thing the user's doing can be described by the following commands, these
+should be the name of the verb:
+
+* `describe` prints detailed information about a single resource. It can include
+  status information of related or child resources, too.
+
+* `list` prints summary information about all resources of a type, possibly
+  filtered by parent or label selector.
+
+* `create` creates a resource. Accepts a `--force` flag to create-or-replace.
+
+* `update` updates a resource based on the changes the user would like to make.
+
+* `delete` deletes a resource
+
+For a given resource there should be parallelism between arguments to `create`
+and `update` as much as possible.
+
+Other domain-specific verbs are possible on a case-by-case basis, like
+`set-traffic` for a Knative Serving Service.
+
+## Arguments
+
+### Positionals
+
+Where there's a single target resource, the resource name should be a positional
+argument. It needs to be of the resource type we're talking about, eg. `kn
+revision` subcommands the positional must be naming a revision.
+
+```bash
+kn service create foo --image gcr.io/things/stuff:tag
+```
+In this case `foo` is positional, and refers to the service to create.
+
+### Flags
+
+* `--force` is a flag on all create commands, and will replace the resource if
+  it already exists (otherwise this is an error). The resource will be *mutated*
+  to have a spec exactly like the resource that would otherwise be created. It
+  is not deleted and recreated.
+
+* When a flag sets a particular field on create or update, it should be a short
+  name for the field, without necessarily specifying how it's nested. For
+  example, `--image=img.repo/asdf` in Knative Serving sets
+  `spec.template.containers[0].image`
+
+#### Output
+
+Commands that output information should support `--output` with a shorthand of
+`-o` to choose how to frame their output, and `--template` for supplying
+templates to output styles that use them.