CLI design: noun-verb vs. verb-noun

[thockin]

Dmitry Berkovich (@dberkov) is working on a proposal around actor lifecycle / state machine / snapshots, and how that maps to API operations and thereby to CLI (to be posted soon, I hope). What I think this lays clear is that there are several imperative-ish operations that we really want to support.

The current CLI (kubectl-ate or as a plugin kubectl ate) follow Kubernetes' convention of VERB-NOUN (e.g. kubectl ate create actor ...). This pattern works great when the majority of use-cases are generic verbs which span many nouns. E.g. kubectl get or kubectl apply or kubectl replace all apply equally to all nouns, and those verbs need no type-specific flags or parameters.

This pattern breaks down as soon as you need more parameters. kubectl create -f works generically (because the object is self-describing), but it also has sub-commands for almost 20 different resources (configmaps, jobs, services, ...) and each sub-command is different from every other. They all have different flags. Worse, it's not possible (AFAIK?) to register a new kubectl plugin under create - only at the root.

Many other CLI tools take the opposite approach - NOUN-VERB. This is more amenable to extension, at the cost of enumerating all the nouns, and at the risk of common functionality being reimplemented many times (e.g. kubectl pod delete and kubectl service delete).

I think we have a couple decisions to make:

1. Should we stick with a kubectl plugin? I'm not sure how much value it offers us given that most of our UXes involve actors or workers, neither of which are kube resources.

2. Should we switch to NOUN-VERB style? I personally think we should. We don't intend to have tons of resources, nor do we think this is likely to be an extensible API. If we really need to generify, we could have both ate delete -f or ate delete <unambiguous-syntax-which-specs-type-and-name> for generic self-describing delete and ate create -f. But actor-centric commands would be in ate actor .... This allows natural things like ate actor suspend and ate actor snapshot and so on, where "suspend" and "snapshot" don't mean anything to other resources (e.g. worker).

[BenTheElder]

Should we stick with a kubectl plugin? I'm not sure how much value it offers us given that most of our UXes involve actors or workers, neither of which are kube resources.

The CLI needs to talk through the kube cluster, there's a lot of scaffolding that comes with operating as a kubectl plugin.

I generally agree that "noun-verb style" is more common and makes more sense generally, but ....

In the context of Kubernetes, the commands we have now are pretty predictable, to the point that my agents have been able to work with kubectl ate effectively immediately. I think that's pretty valuable, at least worth considering: Whatever we come up with should work for simple tasks in a clean session WITHOUT reading an AGENTS.md explaining it.