Commands are confusingly grouped/organized

[dfunckt]

Looking at the CLI command reference, a lot of commands appear to be grouped almost arbitrarily, which doesn’t help with getting an idea of what’s possible (inhibiting discovery) and makes it unnecessarily hard to find the appropriate command for the task at hand (causing confusion). For example, “push” is a single command under its own group. “note” and “logs” which operate on a device are similar.

A better approach is to group commands by the resource they operate on. We’ll need to determine the 5-6 most important/commonly used resources and restructure the commands around them. So, “logs” and “notes” would be subcommands of “device”, “preload” would be a subcommand of “os” (which stands in for an “image” resource, really), etc. I’d argue that “push” partly belongs under “device”, but should at least be alongside “build” and “deploy” (which are their own “Deploy” group, and it’s not that bad, but could just as well be under “release”).

Some commands seem to be grouped by the context they operate in. For example, “join” and “leave”, the “Network” group, and the “Local” group. No one ever thinks “I have a network, what can I do with it?”, but is likely to think instead “I have a device on my local network, what can I do with it?” Going with the same approach as suggested above, most of these should be subcommands under “device”.

It is also confusing that commands are in different groups depending on whether they operate on a single instance of a resource or a collection of them. Eg. there’s a command called “devices” to fetch a bunch of devices, but then all subcommands that operate on one device are nested under “device”. All plural commands (with a singular equivalent) should be a “list” subcommand of their singular equivalent. So “devices” should be “device list”.

The CLI today has the tools needed to allow us to move commands around, while preserving backwards compatibility and minimizing disruption. We should make the changes, create aliases for the previous commands, release a major version, and one or two major versions later remove the aliases to complete the transition.

(I’m loosely jumping back and forth between the actual command namespaces and how they appear in docs. The goal should be for the commands themselves to be properly namespaced first, and the docs should follow with any minor adjustments that they might need.)

@shaunmulligan @otaviojacobi @myarmolinsky @vipulgupta2048