"balena help XXX": command not found

[pdcastro]

Users get confused with the fact that the CLI help command produces output for subcommands, but says "command not found" for top-level commands. Example:

$ balena help os configure
Usage: os configure <image>
Use this command to configure a previously downloaded operating system image for
the specific device or for an application generally.
...

$ balena help os
Command not found: os

The "workaround" is to find out the full command list with balena help -v or on the reference website, then issue balena help for the "full" command (including subcommand).

$ balena help -v
...
    os build-config <image> <device-type> build the OS config and save it to the JSON file
    os configure <image>                  configure an os image
    os download <type>                    download an unconfigured os image
    os initialize <image>                 initialize an os image
    os versions <type>                    show the available balenaOS versions for the given device type

[balena-ci]

[pdcastro] This issue has attached support thread https://jel.ly.fish/#/support-thread~a56f713d-fa21-441f-9446-0e7cd27f5324

[r4space]

This very non-intuitive. Convention means the double word commands look like single word commands where the 2nd word is a parameter not part of the command switch statement (eg, "os download" shouldn't be a command, it should be ~"download-os" or just "download") The fact that alot of commands start with the same word only emphasizes this perception, it all looks like:

devices [option1] <option2>
local [option1] <option2> 
os [option1] <option2>
...etc

I understand making it more standard to any degree could involve alot of effort but a simple quick fix would just be to update the error message (make it print out help per convention) and add an example use '--help'

[pdcastro]

Related to issue #694

[pdcastro]

CC: @srlowe because of recent discussions on balena help conversion to oclif

[srlowe]

Resolved in oclif migration.