Help command

[pith]

The CommandLinePlugin give all the CommandLineHandler to HelpService which extracts CommandLineDescription.
Then the HelpCommandLineHandler inject all the CommandLineDescription and print a well-formated description of all commands or a specific command.

// Internally used by the CommandLinePlugin
class HelpService {
    Map<String, CommandLineDescription> extractDescription(List<Class<CommandLineHandler>> classes);
}

class CommandLineDescription {
    ...
}

class HelpCommandLineHandler {

    @Inject
    private Map<String, CommandLineDescription> descriptionByCommand;

    int call() {
        ...
    }
}

[pith]

I'm open to your propositions for the help message format !

[pith]

I began a branch for this here: https://github.com/pith/seed/tree/cli-help

[ejemba]

Hello @pith I suggest you the following. Because command description can be long. An example with openshift. openshift help will list the commands using their short descriptions.

$ ./openshift help
OpenShift Application Platform

The OpenShift distribution of Kubernetes helps you build, deploy, and manage your applications on top of
Docker containers. To start an all-in-one server with the default configuration, run:

  $ openshift start &

Available Commands:
  start       Launch all-in-one server
  admin       Tools for managing a cluster
  cli         Command line tools for managing applications
  kube        Kubernetes cluster management via kubectl
  ex          Experimental commands under active development
  version     Display version
  help        Help about any command

Use "openshift help <command>" for more information about a given command.
Use "openshift options" for a list of global command-line options (applies to all commands).

whereas openshift help <command> will give the long version. Description can be long so giving ALL the descriptions can be noisy.

$ ./openshift help cli        
Developer and Administrator Client

This client exposes commands for managing your applications, as well as lower level
tools to interact with each component of your system.

To create a new application, you can use the example app source. Login to your server and then
run new-app:

  $ openshift cli login
  $ openshift cli new-app openshift/ruby-20-centos7~https://github.com/openshift/ruby-hello-world.git

This will create an application based on the Docker image 'openshift/ruby-20-centos7' that builds
the source code at 'github.com/openshift/ruby-hello-world.git'. To start the build, run

  $ openshift cli start-build ruby-hello-world --follow

Once your application is deployed, use the status, get, and describe commands to see more about
the created components:

  $ openshift cli status
  $ openshift cli describe deploymentconfig ruby-hello-world
  $ openshift cli get pods

You'll be able to view the deployed application on the IP and port of the service that new-app
created for you.

You can easily switch between multiple projects using 'openshift cli project <projectname>'.

Basic Commands:
  types        An introduction to concepts and types
  login        Log in to a server
  new-project  Request a new project
  new-app      Create a new application
  status       Show an overview of the current project
  project      Switch to another project

Build and Deploy Commands:
  start-build  Starts a new build
  build-logs   Show logs from a build
  deploy       View, start, cancel, or retry a deployment
  rollback     Revert part of an application back to a previous deployment
  new-build    Create a new build configuration
  cancel-build Cancel a pending or running build
  import-image Imports images from a Docker registry
  scale        Change the number of pods in a deployment
  tag          Tag existing images into image streams

Application Modification Commands:
  get          Display one or many resources
  describe     Show details of a specific resource or group of resources
  edit         Edit a resource on the server
  env          Update the environment on a resource with a pod template
  volume       Update volume on a resource with a pod template

            - - - - - - - 8< snip !   - - - - - - - 

Advanced Commands:
  create       Create a resource by filename or stdin
  replace      Replace a resource by filename or stdin.
  patch        Update field(s) of a resource by stdin.
  process      Process a template into list of resources
  export       Export resources so they can be used elsewhere
  run          Run a particular image on the cluster.
  attach       Attach to a running container.
  policy       Manage authorization policy
  secrets      Manage secrets

Settings Commands:
  logout       End the current server session
  config       Change configuration files for the client
  whoami       Return information about the current session

Use "openshift cli help <command>" for more information about a given command.
Use "openshift cli options" for a list of global command-line options (applies to all commands).

As you see a command can be quite long so listing all of them directly could cause bad behaviour.

My 2 cents.

[pith]

@ejemba this was the idea. Look at this test: master...pith:cli-help#diff-0a6422aa48f46841aee827df52ef1dc3R22.

This is just a start but I was planning to have 2 commands:

• help which list all the commands with a short description
• help <cmd> which describe a command in details

[ejemba]

@pith nice.

Did you plan to global introduction description for the blah help and a footer description ?

Perhaps an integrated simple template system in seed elsewhere can be a good thing to format long command.