Mailing-List: contact dev-help@brooklyn.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.incubator.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CABZqRBZHHj5ux9RW0uyPaRt_hUTxc9jDuf88_B_Pu_2w+UemfA@mail.gmail.com>
References: 
 <CAPqc3vfUgck0mbkcfAuhwgUEAkB_ZUk83h9rUf836fBm8YUHUg@mail.gmail.com>
	<564F1921.4060004@gmail.com>
	<2413429A-2BDE-47D7-9943-07F40DC29F5A@cloudsoftcorp.com>
	<23B47729-4F0A-4084-A519-1103ED1C5DDA@cloudsoftcorp.com>
	<CAPqc3vcvBBvY3CK7VYhfAb=KRQEQ813_kTWCaw1u_EYsCaWqUQ@mail.gmail.com>
	<CANaN7bF-Tudc2TQcFu+4CY-VWgrEsC6GAWF+WOuEF4f3a7fNbg@mail.gmail.com>
	<5652DBDE.7080407@CloudsoftCorp.com>
	<5652FC4C.50000@gmail.com>
	<5652FF79.5070407@gmail.com>
	<CAM=AgOwMwt_+5PN0QeaSzwLTLjZT3atk1O4VdO2EBL=vGqVqgg@mail.gmail.com>
	<CABZqRBZHHj5ux9RW0uyPaRt_hUTxc9jDuf88_B_Pu_2w+UemfA@mail.gmail.com>
Date: Tue, 24 Nov 2015 08:50:27 +0000
Message-ID: 
 <CAPqc3vcVBkt+hwRS7etgZ5bF-fNtwCeEzA-b7L0D_-0CnGY3Pw@mail.gmail.com>
Subject: Re: Request for comment on a proposal for a Brooklyn CLI
From: David Lloyd <david.lloyd@cloudsoftcorp.com>
To: dev@brooklyn.incubator.apache.org
Content-Type: multipart/alternative; boundary=047d7b3a8bfaf08d260525456ece

--047d7b3a8bfaf08d260525456ece
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

+1 for option 1 style - but using Mike's suggestion of bk

On 24 November 2015 at 08:25, Mark McKenna <mark.mckenna@cloudsoftcorp.com>
wrote:

> +1 for option 1
> +1 For Mikes suggestion of "bk" over "br"
>
> On Tue, 24 Nov 2015, 00:12 Mike Zaccardo <mike.zaccardo@cloudsoftcorp.com=
>
> wrote:
>
> > +1 `brooklyn` for server
> > +1 2-letter command for client ops, but propose `bk` as the
> abbreviation[1]
> >
> > [1] That's how we New Yorkers do it
> >
> > On Mon, Nov 23, 2015 at 6:59 AM Aled Sage <aled.sage@gmail.com> wrote:
> >
> > > +1 for option (1): "br".
> > >
> > > If we're doing single transferable vote [1], then my second preferenc=
e
> > > would be (3) with the understanding that the brooklyn server-side
> > > command may change substantially when we switch to Karaf. We should
> also
> > > be moving to using something like `service brooklyn start` for the
> > > server-side, so we could live with the name clash in the mean time.
> > >
> > > Aled
> > >
> > > [1] http://www.electoral-reform.org.uk/single-transferable-vote
> > >
> > >
> > > On 23/11/2015 11:45, Hadrian Zbarcea wrote:
> > > > I also like 'brooky' for some weird reason, but +1 for 'br'.
> > > >
> > > > Hadrian
> > > >
> > > > On 11/23/2015 04:26 AM, Alex Heneveld wrote:
> > > >>
> > > >> There is a trend towards 2LAs (two-letter acronyms) for commands i=
n
> > > >> devops -- for instance `cf` and `tf` and of course `go`.  We alrea=
dy
> > > >> have `brooklyn` as a CLI for the *server*; however it does take a
> > > >> `launch` argument so we could overload it:
> > > >>
> > > >>      brooklyn launch   # launch a server on localhost (new
> > > >> implementation as go command calling to some java)
> > > >>      brooklyn login URL     # connect to a server somewhere
> > > >>      brooklyn list                  #
> > > >>
> > > >> Though that is a bit confusing IMO.  Or of course we could rename
> > > >> existing bin/brooklyn as brooklyn-server, or go with broo.
> > > >>
> > > >> Seems to me we have several options:
> > > >>
> > > >> 1) Use `br` for client operations and `brooklyn` for server
> (original
> > > >> proposal)
> > > >> 2) Use `broo` for client operations and `brooklyn` for server
> (Svet's
> > > >> proposal)
> > > >> 3) Use `brooklyn` for both server and client operations (Andrea's
> > > >> proposal, expanded above)
> > > >> 4) Use `brooklyn` for client operations and `brooklyn-server` for
> > server
> > > >> operations (mod of Andrea's proposal)
> > > >>
> > > >> I'm for "1" -- in my usage the 2LAs become very natural, and we're
> > lucky
> > > >> that `br` is not a known *nix command.  (And I don't think there i=
s
> > that
> > > >> much potential for confusion with the HTML tag.)
> > > >>
> > > >> Best
> > > >> Alex
> > > >>
> > > >>
> > > >> On 20/11/2015 14:32, Andrea Turli wrote:
> > > >>> I agree with Svet, `br` sounds weird (too similar to <br> :) ) Wh=
y
> > > >>> `brooklyn` is not good? I think autocompletion will help and
> > `brooklyn`
> > > >>> will be more mnemonic, maybe.
> > > >>>
> > > >>> My minor comment,
> > > >>> Andrea
> > > >>>
> > > >>> On Fri, 20 Nov 2015 at 14:28 David Lloyd
> > > >>> <david.lloyd@cloudsoftcorp.com>
> > > >>> wrote:
> > > >>>
> > > >>>> The existing CLI caches the login details (URL, username,
> password)
> > > >>>> in file
> > > >>>> ~/.brooklyn_cli, so I guess that we'll look initially at caching
> the
> > > >>>> other
> > > >>>> IDs in this file.
> > > >>>>
> > > >>>> Dave.
> > > >>>>
> > > >>>> On 20 November 2015 at 13:18, Svetoslav Neykov <
> > > >>>> svetoslav.neykov@cloudsoftcorp.com> wrote:
> > > >>>>
> > > >>>>> I see many of the commands using context (the cached entity).
> Where
> > > >>>>> does
> > > >>>>> the context go into? Can parallel shells calling into the cli
> have
> > > >>>>> different contexts?
> > > >>>>> Perhaps we should keep the CLI context free and present the use=
r
> > > >>>>> with a
> > > >>>>> console for where context is needed (something similar to
> > > >>>>> http://htty.github.io/htty/)?
> > > >>>>>
> > > >>>>> Personal preference to naming the executable broo.
> > > >>>>>
> > > >>>>> +1 to having aliases for where context is allowed, but should b=
e
> > > >>>>> careful
> > > >>>>> with the lifetime of the aliases.
> > > >>>>>
> > > >>>>> Svet.
> > > >>>>>
> > > >>>>>
> > > >>>>>> On 20.11.2015 =D0=B3., at 15:06, Geoff Macartney <
> > > >>>>> geoff.macartney@cloudsoftcorp.com> wrote:
> > > >>>>>> Perhaps we could have an =E2=80=9Calias=E2=80=9D command for a=
pplications etc,
> > > >>>> something
> > > >>>>> like
> > > >>>>>> br application  list
> > > >>>>>> =E2=80=A6.// view the list of applications
> > > >>>>>> br application  alias  myserver  ID12ab
> > > >>>>>> br application myserver  add  abc.yaml
> > > >>>>>> br application myserver  add  def.yaml
> > > >>>>>> br application myserver  add  xyz.yaml
> > > >>>>>>
> > > >>>>>>
> > > >>>>>> =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=
=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=
=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94
> > > >>>>>> Gnu PGP key - http://is.gd/TTTTuI
> > > >>>>>>
> > > >>>>>>
> > > >>>>>>> On 20 Nov 2015, at 12:59, Aled Sage <aled.sage@gmail.com>
> wrote:
> > > >>>>>>>
> > > >>>>>>> Thanks,
> > > >>>>>>>
> > > >>>>>>> This looks really good.
> > > >>>>>>>
> > > >>>>>>> It will be great to have this, and to have a getting started
> > guide
> > > >>>> that
> > > >>>>> is based on this new CLI. Many other tools in the devops space
> > > >>>>> focus on
> > > >>>>> this kind of client CLI (e.g. Docker, Cloud Foundry, etc).
> > > >>>>>>> ---
> > > >>>>>>> I'm not sure about the "br application cache <ID>", which set=
s
> > the
> > > >>>>>>> app
> > > >>>>> id to be used for subsequent calls such as "br entity ...". If
> > using
> > > >>>>> IDs
> > > >>>>> they are globally unique, so we could just miss out the app id
> > (we'd
> > > >>>>> need
> > > >>>>> to add to the REST api to support that).
> > > >>>>>>> Would we want to support logical names for apps/entities,
> rather
> > > >>>>>>> than
> > > >>>>> just IDs? The REST api supports looking up the app by its displ=
ay
> > > >>>>> name.
> > > >>>> I'm
> > > >>>>> not convinced we want to do that, but it certainly is
> simple/useful
> > > >>>>> sometimes to use logical names.
> > > >>>>>>> Aled
> > > >>>>>>>
> > > >>>>>>>
> > > >>>>>>> On 20/11/2015 12:14, David Lloyd wrote:
> > > >>>>>>>> Hi All,
> > > >>>>>>>>
> > > >>>>>>>> We=E2=80=99ve been thinking that it would be really useful f=
or
> Brooklyn
> > to
> > > >>>>> have a
> > > >>>>>>>> tool that provides a Command Line Interface (CLI) to augment
> the
> > > >>>>> current
> > > >>>>>>>> web based GUI and REST API. The proposal below outlines what
> we
> > > >>>>>>>> are
> > > >>>>>>>> thinking of.  We request comments from the community on the
> > idea,
> > > >>>>>>>> and
> > > >>>>> would
> > > >>>>>>>> very much welcome suggestions for developing it.
> > > >>>>>>>>
> > > >>>>>>>> Comments can be made by replying to this email or by adding
> > > >>>>>>>> comment/suggestions to this document:
> > > >>>>>>>>
> > > >>>>
> > >
> >
> https://docs.google.com/document/d/1KNCHG--ExGevcGoJ3cRzcrjh3mWsZOzyCzRM_=
TpoGGo/edit?usp=3Dsharing
> > > >>>>
> > > >>>>
> > > >>>>>>>> (and there are two comments on the document already)
> > > >>>>>>>>
> > > >>>>>>>>
> > > >>>>>>>> Description of Proposal
> > > >>>>>>>>
> > > >>>>>>>> The current REST API provides a powerful way for controlling
> > > >>>> Brooklyn,
> > > >>>>> but
> > > >>>>>>>> it is difficult to combine operations (using the output of a
> > > >>>>>>>> command
> > > >>>> as
> > > >>>>>>>> input to a second command) using the GUI or using the REST A=
PI
> > > >>>>>>>> on a
> > > >>>>> command
> > > >>>>>>>> line.  We think that having a dedicated command line tool
> would
> > > >>>>>>>> make
> > > >>>> it
> > > >>>>>>>> easier for beginners and advanced users to control Brooklyn.
> > > >>>>>>>>
> > > >>>>>>>> Robert Moss has already done some excellent work on the =E2=
=80=98Go
> CLI
> > > >>>> client
> > > >>>>> for
> > > >>>>>>>> Brooklyn REST API=E2=80=99 which can be found at
> > > >>>>> brooklyncentral/brooklyn-cli.  Our
> > > >>>>>>>> intention with this proposal would be to build upon this wor=
k
> > and
> > > >>>>> implement
> > > >>>>>>>> a set of commands that go beyond mirroring the REST API.  We
> > > >>>>>>>> feel it
> > > >>>>> would
> > > >>>>>>>> be best to keep the CLI in its own repo (so it can follow th=
e
> Go
> > > >>>>>>>> conventions), for example with the name brooklyn-cli.
> > > >>>>>>>>
> > > >>>>>>>> We think that it is important for a CLI to be portable and t=
o
> > > >>>>>>>> have as
> > > >>>>> few
> > > >>>>>>>> (if any) dependencies on other tools as possible.  Go has th=
e
> > > >>>>> advantages of
> > > >>>>>>>> compiling to native OS specific binaries that are statically
> > > >>>>>>>> linked,
> > > >>>> so
> > > >>>>>>>> avoids the need for installing dependencies (and getting the
> > right
> > > >>>>>>>> combination of versions!).  It can also be compiled for
> multiple
> > > >>>>> operating
> > > >>>>>>>> systems, enabling a CLI to be built for servers and typical
> end
> > > >>>>>>>> user
> > > >>>>>>>> systems.
> > > >>>>>>>>
> > > >>>>>>>> Some possible commands that the CLI may provide include:
> > > >>>>>>>>
> > > >>>>>>>> br login
> > > >>>>>>>>
> > > >>>>>>>> cache login credentials for the Brooklyn instance
> > > >>>>>>>>
> > > >>>>>>>> br application list
> > > >>>>>>>>
> > > >>>>>>>> show the list of applications
> > > >>>>>>>>
> > > >>>>>>>> br application show <ID>
> > > >>>>>>>>
> > > >>>>>>>> show details of application <ID>
> > > >>>>>>>>
> > > >>>>>>>> br application cache <ID>
> > > >>>>>>>>
> > > >>>>>>>> cache the application <ID> to be used with subsequent comman=
ds
> > > >>>>>>>> that
> > > >>>>> require
> > > >>>>>>>> an application ID.
> > > >>>>>>>>
> > > >>>>>>>> br application add <file|url>
> > > >>>>>>>>
> > > >>>>>>>> add (deploy) the specified application blueprint
> > > >>>>>>>>
> > > >>>>>>>> br entity list [-r]
> > > >>>>>>>>
> > > >>>>>>>> list the entities for an application, recursively if =E2=80=
=98-r=E2=80=99
> > > >>>>>>>> specified
> > > >>>>>>>> (having previously used =E2=80=98br application cache <ID>=
=E2=80=99)
> > > >>>>>>>>
> > > >>>>>>>> br entity show <ID>
> > > >>>>>>>>
> > > >>>>>>>> show the details for an entity
> > > >>>>>>>>
> > > >>>>>>>> br entity cache <ID>
> > > >>>>>>>>
> > > >>>>>>>> cache the entity <ID> to be used with subsequent commands th=
at
> > > >>>> require
> > > >>>>> an
> > > >>>>>>>> entity ID (to be discarded if a new application ID is set).
> > > >>>>>>>>
> > > >>>>>>>> br sensor list
> > > >>>>>>>>
> > > >>>>>>>> list the sensors for an application / entity
> > > >>>>>>>>
> > > >>>>>>>> (having previously used =E2=80=98br application cache <ID>=
=E2=80=99 and =E2=80=98br
> > entity
> > > >>>>> cache
> > > >>>>>>>> <ID>=E2=80=99)
> > > >>>>>>>>
> > > >>>>>>>> br sensor show <Name>
> > > >>>>>>>>
> > > >>>>>>>> show the sensor value
> > > >>>>>>>>
> > > >>>>>>>> br sensor show service.isUp
> > > >>>>>>>>
> > > >>>>>>>> show the value of the service.isUp sensor on the previously
> > > >>>>>>>> specified
> > > >>>>>>>> application / entity
> > > >>>>>>>>
> > > >>>>>>>> br effector list
> > > >>>>>>>>
> > > >>>>>>>> list the effectors for an application / entity
> > > >>>>>>>>
> > > >>>>>>>> br effector invoke <Name> "{<parameter map>}"
> > > >>>>>>>>
> > > >>>>>>>> run the effector <Name> for a previously cached application
> > <ID> /
> > > >>>>> entity
> > > >>>>>>>> <ID>
> > > >>>>>>>>
> > > >>>>>>>> br catalog list
> > > >>>>>>>>
> > > >>>>>>>> show the list of available catalog items
> > > >>>>>>>>
> > > >>>>>>>> br catalog add <file|url>
> > > >>>>>>>>
> > > >>>>>>>> add the specified catalog entries
> > > >>>>>>>>
> > > >>>>>>>> br location list
> > > >>>>>>>>
> > > >>>>>>>> list the available locations
> > > >>>>>>>>
> > > >>>>>>>> br location show <ID>
> > > >>>>>>>>
> > > >>>>>>>> show details for location <ID>
> > > >>>>>>>>
> > > >>>>>>>> br location add "{locationSpec}"
> > > >>>>>>>>
> > > >>>>>>>> add the specified location
> > > >>>>>>>>
> > > >>>>>>>> It is intended that further commands would be added later su=
ch
> > as:
> > > >>>>>>>>
> > > >>>>>>>>    -
> > > >>>>>>>>
> > > >>>>>>>>    br policy =E2=80=A6
> > > >>>>>>>>    -
> > > >>>>>>>>
> > > >>>>>>>>    br activity =E2=80=A6
> > > >>>>>>>>    -
> > > >>>>>>>>
> > > >>>>>>>>    etc.
> > > >>>>>>>>
> > > >>>>>>>>
> > > >>>>>>>> Existing CLI
> > > >>>>>>>>
> > > >>>>>>>> For reference the implemented commands for the existing
> > > >>>>>>>> brooklyn-cli
> > > >>>>> are:
> > > >>>>>>>> USAGE:
> > > >>>>>>>>
> > > >>>>>>>>   br [global options] command [command options] [arguments..=
.]
> > > >>>>>>>>
> > > >>>>>>>> VERSION:
> > > >>>>>>>>
> > > >>>>>>>>   0.0.0
> > > >>>>>>>>
> > > >>>>>>>> COMMANDS:
> > > >>>>>>>>
> > > >>>>>>>>   access Show access control
> > > >>>>>>>>
> > > >>>>>>>>   activity Show the activity for an entity
> > > >>>>>>>>
> > > >>>>>>>>   activity-children Show the child activities for an entity
> > > >>>>>>>>
> > > >>>>>>>>   activity-stream Show the stream for a given activity
> > > >>>>>>>>
> > > >>>>>>>>   add-catalog Add a new catalog item from the supplied YAML
> > > >>>>>>>>
> > > >>>>>>>>   add-children Add a child or children to this entity from t=
he
> > > >>>> supplied
> > > >>>>> YAML
> > > >>>>>>>>   application Show the status and location of a running
> > > >>>>>>>> application
> > > >>>>>>>>
> > > >>>>>>>>   applications Show the status and location of running
> > > >>>>>>>> applications
> > > >>>>>>>>
> > > >>>>>>>>   catalog List the available catalog applications
> > > >>>>>>>>
> > > >>>>>>>>   config Show the config for an application and entity
> > > >>>>>>>>
> > > >>>>>>>>   create Create a new brooklyn application from the supplied
> > YAML
> > > >>>>>>>>
> > > >>>>>>>>   delete Delete a brooklyn application
> > > >>>>>>>>
> > > >>>>>>>>   destroy-policy Destroy a policy
> > > >>>>>>>>
> > > >>>>>>>>   effectors Show the list of effectors for an application an=
d
> > > >>>>>>>> entity
> > > >>>>>>>>
> > > >>>>>>>>   entities Show the entites for an application
> > > >>>>>>>>
> > > >>>>>>>>   entity-children Show the children of an application's enti=
ty
> > > >>>>>>>>
> > > >>>>>>>>   locations List the available locations
> > > >>>>>>>>
> > > >>>>>>>>   login Login to brooklyn
> > > >>>>>>>>
> > > >>>>>>>>   policies Show the list of policies for an application and
> > entity
> > > >>>>>>>>
> > > >>>>>>>>   policy Show the status of a policy for an application and
> > entity
> > > >>>>>>>>
> > > >>>>>>>>   rename-entity Rename an entity
> > > >>>>>>>>
> > > >>>>>>>>   sensor Show the value of a sensor for an application and
> > entity
> > > >>>>>>>>
> > > >>>>>>>>   sensors Show the sensors for an application and entity
> > > >>>>>>>>
> > > >>>>>>>>   set-config Set config for an entity
> > > >>>>>>>>
> > > >>>>>>>>   spec Get the YAML spec used to create the entity, if
> available
> > > >>>>>>>>
> > > >>>>>>>>   start-policy Start or resume a policy
> > > >>>>>>>>
> > > >>>>>>>>   stop-policy Suspends a policy
> > > >>>>>>>>
> > > >>>>>>>>   tree Show the tree of all applications
> > > >>>>>>>>   version Display the version of the connected Brooklyn
> > > >>>>>>>>
> > > >>>>>>>>
> > > >>>>>>>> Geoff Macartney (geoff.macartney@cloudsoft.io)
> > > >>>>>>>> David Lloyd (david.lloyd@cloudsoft.io)
> > > >>>>>>>>
> > > >>>>>
> > > >>
> > >
> > >
> >
> --
>
> *Mark McKenna*
>
> *Twitter :: @m4rkmckenna <https://twitter.com/m4rkmckenna>*
>
> *PGP :: public-key
> <https://pgp.mit.edu/pks/lookup?op=3Dget&search=3D0x2B5DC759B1EB76A7>*
>

--047d7b3a8bfaf08d260525456ece--