CLI Proposal

We want a grown-up command-line set of tools for brooklyn, to facilitate starting applications and give users the right understanding from the outset.

This proposal is based on discussions on the mailing list, where we seemed to tend towards this approach, as well as my (Alex's) experience using it and working with users. (References at the end.)

Illustration

Syntax to start an app is:

brooklyn-server --classpath ~/brooklyn/myproj/target/classes start &
brooklyn deploy com.myproj.MyProjApp

or

brooklyn --embedded --classpath ~/brooklyn/myproj/target/classes deploy com.myproj.MyProjApp

Intention of course is that it be extremely straightforward to download, untar, and run. Or can be run in a dev environment.

Commands

We've settled on two commands, one for server (suggesting brooklyn-server, although brooklynd and brooklyn-bridge have also been proposed) and one for client, both using a git-like interface.

brooklyn-server
        manages a brooklyn server instance (on the local machine)
  --classpath XXX,XXX   // additional classes to have on classpath at startup
  start
    --rest-port PORT    // default "8080+"
    --no-rest
    --gui-port PORT     // default "8081+"
    --no-gui
  stop
        stop all subsystems (or selected ones)
    --rest, --gui       // stop indicated subsystems only
  status
        outputs text and result code for whether the server is running
        (based on output of PIDs and PORTs written to a well-known file location?)
        (?? -- not sure if we need this, but seems like it should be useful)

brooklyn
        runs commands against a server
  --embedded (start a simple embedded local web server)
  --endpoint URL        // REST endpoint, default "http://localhost:8181"
  --retry TIME          // will retry connection to the endpoint for this time period, default "30s"
  --no-retry            // won't retry connection
  deploy APP
        deploys the specified application using given config, classpath, location, etc
        where APP can be
            . a fully qualified class-name of something on the classpath
            . path or URL to a script file (if ends .groovy)
            . path or URL to a JSON file (if ends .json)
    --format XXX        // either json,groovy,class, to force APP type detection
    --no-start          // don't invoke `start` on the application
    --location, --locations XXX,XXX,XXX
    --config A=B,C=D    // pass these config parameters to the application
    --classpath XXX,XXX     // upload the given classes (for this app only?)
  undeploy APP
    --no-stop           // don't invoke `stop` on the application

Additionally, both support:

{brooklyn,brooklyn-server}
  help, --help, -h, and no arguments     // display help, possibly after a command for more detailed help
  version, --version, -v                 // print version

And some syntax details (not sure about these, but we need to decide one way or another):

• Commands can not be combined; it's basically one-shot fire-and-forget to do something
• Long-arg options can occur anywhere in the command (i.e. you can write brooklyn --location LOC deploy APP or brooklyn deploy --location LOC APP or brooklyn deploy APP --location LOC) except of course as an argument to a long-arg (brooklyn --location --endpoint URL LOC will give a syntax error because it interprets --endpoint as the location string, and doesn't know how to parse the options URL LOC)

Other Essentials

• REST endpoint security -- username and password? token? re-use simple *SecurityProvider classes in existing GUI implementation?
• Brooklyn client will retry to connect to the server for up to 30s (to allow scripts to immediately start one than the other)
• Document the classpath isolation and upload model
• Document how to supply custom logging conf (classpath? dedicated CLI option? filesystem conf structure?)
• Logging during start sequence, useful info at INFO (but not too much)
• Command-line tools should be able to run (a) from symbolic links e.g. in /usr/bin dir (resolving the path with readlink) with no env requirements; or (d) by typing the full path to brooklyn (doesn't assume it's in CWD); or (c) with BROOKLYN_HOME set (not autodetecting any paths); also (d) we might allow BROOKLYN_OPTS and BROOKLYN_CLASSPATH to override defaults in the scripts
• Update all the examples (with a README.txt) and documention (web site markdown) so that they advise using brooklyn --classpath "target/classes:target/lib/*.jar" deploy XXX (ie don't have any scripts), or even somehow a single export BROOKLYN_CLASSPATH=xxx so that all examples run, if possible

Deferred for the Moment

I suggest focussing on the above as a first pass, but I think we want these soon and worth making sure we can support these elegantly. (Which I think we can.)

• APP nicknames (could we just search for a unqualified class name)
• interactive shell and multiple commands
• OSGi support (for proper versioning)
• REST commands, e.g. list apps, entities, etc show entityByIdOrName, sensors, etc invoke effector arg1=val2 arg2=val2
• Federation, via a --endpoint on the server to connect to existing server (once federated mgmt plane implement)

References

• Google doc by @grkvlt: https://docs.google.com/document/d/19Vx4xelxG2nPk6X0Mv-F-Jw431nqUvt4opSbHnyODQc/edit#
• brooklyn-dev discussion (subject: brooklyn CLI discussion)