Mailing List Archive

Reminds me of the Opsware Global Shell. That was built on a FUSE fs
interface to the API. I loved it when I worked on it.

-Matt

On Wed, Apr 18, 2012 at 11:07 PM, Dean Troyer <dtroyer@gmail.com> wrote:
> We had a good discussion about a unified OpenStack command line client
> on Monday at the Design Summit.  The notes are in the Etherpad at
> http://etherpad.openstack.org/FolsumCLI, I summarized my recollection
> at the bottom; those who were there feel free to add the bits I
> missed.
>
> One of the first things to do is to find out who is interested in
> contributing to this project.and hopefully coordinating some of the
> work with the other emerging project-specific clients.  Send me an
> email and I'll build a list to get the discussion started.
>
> We also should look for some consensus on the name of the command
> itself.  'oscli' is a placeholder, and while sufficiently short and
> unique for my tastes it is hard to pronounce and remember.  The
> leading candidates I have heard at the summit so far are 'openstack'
> and 'stack'.  Let's gather some feedback at the bottom of the Etherpad
> about this as I am sure there are other opinions out there.
>
> Thanks
> dt
>
> --
>
> Dean Troyer
> dtroyer@gmail.com
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Wed, Apr 18, 2012 at 11:07 PM, Dean Troyer <dtroyer@gmail.com> wrote:

> We had a good discussion about a unified OpenStack command line client
> on Monday at the Design Summit. The notes are in the Etherpad at
> http://etherpad.openstack.org/FolsumCLI, I summarized my recollection
> at the bottom; those who were there feel free to add the bits I
> missed.
>
> One of the first things to do is to find out who is interested in
> contributing to this project.and hopefully coordinating some of the
> work with the other emerging project-specific clients. Send me an
> email and I'll build a list to get the discussion started.
>

Count me in.


>
> We also should look for some consensus on the name of the command
> itself. 'oscli' is a placeholder, and while sufficiently short and
> unique for my tastes it is hard to pronounce and remember. The
> leading candidates I have heard at the summit so far are 'openstack'
> and 'stack'. Let's gather some feedback at the bottom of the Etherpad
> about this as I am sure there are other opinions out there.
>
> Thanks
> dt
>
> --
>
> Dean Troyer
> dtroyer@gmail.com
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help : https://help.launchpad.net/ListHelp
>

I'd be down with helping out as well.

On Thu, Apr 19, 2012 at 1:43 PM, Doug Hellmann
<doug.hellmann@dreamhost.com> wrote:
>
>
> On Wed, Apr 18, 2012 at 11:07 PM, Dean Troyer <dtroyer@gmail.com> wrote:
>>
>> We had a good discussion about a unified OpenStack command line client
>> on Monday at the Design Summit.  The notes are in the Etherpad at
>> http://etherpad.openstack.org/FolsumCLI, I summarized my recollection
>> at the bottom; those who were there feel free to add the bits I
>> missed.
>>
>> One of the first things to do is to find out who is interested in
>> contributing to this project.and hopefully coordinating some of the
>> work with the other emerging project-specific clients.  Send me an
>> email and I'll build a list to get the discussion started.
>
>
> Count me in.
>
>>
>>
>> We also should look for some consensus on the name of the command
>> itself.  'oscli' is a placeholder, and while sufficiently short and
>> unique for my tastes it is hard to pronounce and remember.  The
>> leading candidates I have heard at the summit so far are 'openstack'
>> and 'stack'.  Let's gather some feedback at the bottom of the Etherpad
>> about this as I am sure there are other opinions out there.
>>
>> Thanks
>> dt
>>
>> --
>>
>> Dean Troyer
>> dtroyer@gmail.com
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

I'm interested as well.

I wasn't able to attend the session, but I'd like to see something akin to the proposed Human Interface Guideline <http://wiki.openstack.org/Design> for the CLI to ensure that the implementation achieves the goals spelled out in the Etherpad.

Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com





On Apr 19, 2012, at 1:57 PM, Matt Joyce wrote:

> I'd be down with helping out as well.
>
> On Thu, Apr 19, 2012 at 1:43 PM, Doug Hellmann
> <doug.hellmann@dreamhost.com> wrote:
>>
>>
>> On Wed, Apr 18, 2012 at 11:07 PM, Dean Troyer <dtroyer@gmail.com> wrote:
>>>
>>> We had a good discussion about a unified OpenStack command line client
>>> on Monday at the Design Summit. The notes are in the Etherpad at
>>> http://etherpad.openstack.org/FolsumCLI, I summarized my recollection
>>> at the bottom; those who were there feel free to add the bits I
>>> missed.
>>>
>>> One of the first things to do is to find out who is interested in
>>> contributing to this project.and hopefully coordinating some of the
>>> work with the other emerging project-specific clients. Send me an
>>> email and I'll build a list to get the discussion started.
>>
>>
>> Count me in.
>>
>>>
>>>
>>> We also should look for some consensus on the name of the command
>>> itself. 'oscli' is a placeholder, and while sufficiently short and
>>> unique for my tastes it is hard to pronounce and remember. The
>>> leading candidates I have heard at the summit so far are 'openstack'
>>> and 'stack'. Let's gather some feedback at the bottom of the Etherpad
>>> about this as I am sure there are other opinions out there.
>>>
>>> Thanks
>>> dt
>>>
>>> --
>>>
>>> Dean Troyer
>>> dtroyer@gmail.com
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to : openstack@lists.launchpad.net
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help : https://help.launchpad.net/ListHelp
>>
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to : openstack@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help : https://help.launchpad.net/ListHelp
>>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help : https://help.launchpad.net/ListHelp

Dean Troyer (dtroyer@gmail.com) wrote:
> We had a good discussion about a unified OpenStack command line client
> on Monday at the Design Summit. The notes are in the Etherpad at
> http://etherpad.openstack.org/FolsumCLI, I summarized my recollection
> at the bottom; those who were there feel free to add the bits I
> missed.
>
> One of the first things to do is to find out who is interested in
> contributing to this project.and hopefully coordinating some of the
> work with the other emerging project-specific clients. Send me an
> email and I'll build a list to get the discussion started.

I missed the session but I'm interested in this and should be able to
contribute a few opinions at the very least, and hopefully some
commits too (I'm already working on unifying help output across
various commands).

> We also should look for some consensus on the name of the command
> itself. 'oscli' is a placeholder, and while sufficiently short and
> unique for my tastes it is hard to pronounce and remember. The
> leading candidates I have heard at the summit so far are 'openstack'
> and 'stack'. Let's gather some feedback at the bottom of the Etherpad
> about this as I am sure there are other opinions out there.

I have added my votes, tidied up the voting text in the etherpad (it
was a little unclear which were total vote counts vs. individual
votes), and suggested another possibility: 'ost', although FWIW I
prefer 'openstack' which is unambiguous, obvious, and unforgettable.
Bearing in mind Murphy's Law, whatever 3- or 4-letter abbreviation you
choose, there's a chance it's already been claimed for some other
purpose in at least one environment somewhere :-) For example, in an
Ubuntu world, someone might really like 'osc' because it's fast to
type and fairly easy to remember ("OpenStack CLI") ... but in a SUSE
world, that would be full of fail because osc is already heavily used
as the CLI for the Open Build Service. So keeping it as 'openstack'
would allow Ubuntu folk (in this example) to do 'alias osc=openstack'
and SUSE folk to do (say) 'alias ost=openstack'.

Thanks!
Adam

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

Dean Troyer (dtroyer@gmail.com) wrote:
> One of the first things to do is to find out who is interested in
> contributing to this project.and hopefully coordinating some of the
> work with the other emerging project-specific clients. Send me an
> email and I'll build a list to get the discussion started.

Count me in - by 'build a list' do you mean a new mailing list?

I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
(which looks like a great start on the topic!) and made some minor
tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I
wanted to make a few suggestions before I forget - can always continue
discussion elsewhere if appropriate:

1. Regarding "The subject names are always specified in command in
their singular form. This is contrary to natural language use."

- I didn't understand the second sentence here, but shouldn't the
HIG should allow for scenarios where the verb can operate both on
individual objects and on multiple objects in batch?

(Grammatical nitpick: if the verb is acting on the noun, then the
HIG should refer to the noun as "object" rather than "subject".)

2. I think it would be good if the HIG gave guidelines on how the
command should behave when run with no arguments.

3. I think it would be good if the HIG recommended that, at least
when subcommands are permitted, single arguments '--help' and
'help' always generate identical output:

https://bugs.launchpad.net/keystone/+bug/936399
https://review.openstack.org/#/c/6460/

4. I think it would be good if the HIG gave guidelines on how the
help text should be formatted - in particular that positional
arguments are covered by the help text (e.g. keystone-manage does
not currently give any info on positional arguments required
until you specify too few).

5. I think it would be good if the HIG specified what sort of help
text should be included alongside error messages of (say) the
"you didn't give the right number of arguments" variety, and
whether the error message should appear before or after that help
text. My vote is after, because it's far easier for the human
eye to locate the end of a command's output than the beginning,
especially if the beginning has scrolled off the top of the
terminal.

Thanks,
Adam

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

>
>  2. I think it would be good if the HIG gave guidelines on how the
>     command should behave when run with no arguments.

I think the marines call this sort of thing, Task Condition and
Standard. Not sure how useful it would be.

>  3. I think it would be good if the HIG recommended that, at least
>     when subcommands are permitted, single arguments '--help' and
>     'help' always generate identical output:
>
>       https://bugs.launchpad.net/keystone/+bug/936399
>       https://review.openstack.org/#/c/6460/

Same for Version ( --version )

>  5. I think it would be good if the HIG specified what sort of help
>     text should be included alongside error messages of (say) the
>     "you didn't give the right number of arguments" variety, and
>     whether the error message should appear before or after that help
>     text.  My vote is after, because it's far easier for the human
>     eye to locate the end of a command's output than the beginning,
>     especially if the beginning has scrolled off the top of the
>     terminal.

I wonder if this event tracking is relevant to metering. At the very
least it could be relevant to an audit log / revision history.

Curious if that's outside the scope of the CLI. For one, I believe
it would be worthwhile to be able to integrate with the APIs to
provide a recall of past events and results.

-Matt

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@suse.com> wrote:

> Dean Troyer (dtroyer@gmail.com) wrote:
> > One of the first things to do is to find out who is interested in
> > contributing to this project.and hopefully coordinating some of the
> > work with the other emerging project-specific clients. Send me an
> > email and I'll build a list to get the discussion started.
>
> Count me in - by 'build a list' do you mean a new mailing list?
>
> I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
> (which looks like a great start on the topic!) and made some minor
> tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I
> wanted to make a few suggestions before I forget - can always continue
> discussion elsewhere if appropriate:
>
> 1. Regarding "The subject names are always specified in command in
> their singular form. This is contrary to natural language use."
>
> - I didn't understand the second sentence here, but shouldn't the
> HIG should allow for scenarios where the verb can operate both on
> individual objects and on multiple objects in batch?
>

I read that as meaning the command to list instances available to a tenant
should be "list server" not the more natural "list servers".

Can you give an example of a command that would work on multiple objects in
batch?


>
> (Grammatical nitpick: if the verb is acting on the noun, then the
> HIG should refer to the noun as "object" rather than "subject".)
>
> 2. I think it would be good if the HIG gave guidelines on how the
> command should behave when run with no arguments.
>

Running a cliff-based app without any arguments enters "interactive" mode
(as of 0.4) which gives the user a new prompt and lets them run multiple
commands before exiting. This is intended to be used as an optimization for
commands to cache authentication credentials and clients and avoid logging
in for every sub-command.

Since we're using argparse for the subcommands, the default behavior if a
command is run without arguments depends on the subcommand. If the
subcommand has no required arguments, it will do whatever it is meant to
do. If it does require arguments and sees none, argparse prints an error
message about whatever is missing (and possibly suggests that the user use
--help to get instructions).


>
> 3. I think it would be good if the HIG recommended that, at least
> when subcommands are permitted, single arguments '--help' and
> 'help' always generate identical output:
>
> https://bugs.launchpad.net/keystone/+bug/936399
> https://review.openstack.org/#/c/6460/


The current version of cliff eats the --help option no matter where it
appears on the command line, so to get help on a subcommand you always have
to use "help" (without the dashes).

$ openstack --help
$ openstack list server --help

both print the help for the "openstack" command, including a list of
available subcommands

$ openstack help list server

prints the help for the "list server" subcommand of "openstack"


> 4. I think it would be good if the HIG gave guidelines on how the
> help text should be formatted - in particular that positional
> arguments are covered by the help text (e.g. keystone-manage does
> not currently give any info on positional arguments required
> until you specify too few).
>

Do we need to specify this beyond saying that all subcommands must use
argparse for argument parsing (the new framework depends on it anyway, and
then they are all consistent)?


>
> 5. I think it would be good if the HIG specified what sort of help
> text should be included alongside error messages of (say) the
> "you didn't give the right number of arguments" variety, and
> whether the error message should appear before or after that help
> text. My vote is after, because it's far easier for the human
> eye to locate the end of a command's output than the beginning,
> especially if the beginning has scrolled off the top of the
> terminal.


> Thanks,
> Adam
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help : https://help.launchpad.net/ListHelp
>

On Mon, Apr 30, 2012 at 11:13 AM, Adam Spiers <aspiers@suse.com> wrote:
> Count me in - by 'build a list' do you mean a new mailing list?

You're in! For now that's just a list I'm keeping.

> tweaks.  Should we discuss the FIXMEs you marked here or elsewhere?  I
> wanted to make a few suggestions before I forget - can always continue
> discussion elsewhere if appropriate:

This is it for now except for what we may do in the wiki itself while
writing the doc. There is activity going on that may shift traffic on
the lists. One of the things that will happen is the addition of
prefixes in the subject so we can start by using [client].

>  1. Regarding "The subject names are always specified in command in
>     their singular form.  This is contrary to natural language use."
>
>       - I didn't understand the second sentence here, but shouldn't the
>         HIG should allow for scenarios where the verb can operate both on
>         individual objects and on multiple objects in batch?

I was referring to 'list server' vs 'list servers'. It would be nice
to accept either where plural is natural, but that is a lower priority
thing to solve.

>     (Grammatical nitpick: if the verb is acting on the noun, then the
>     HIG should refer to the noun as "object" rather than "subject".)

That was a deliberate choice based on how overloaded the word 'object'
is in programming. My HS English teacher is preparing a detention for
me I'm sure...

>  2. I think it would be good if the HIG gave guidelines on how the
>     command should behave when run with no arguments.

For some commands that is totally valid, for some that is an error
condition. This probably belongs with the specific command
definitions.

>  3. I think it would be good if the HIG recommended that, at least
>     when subcommands are permitted, single arguments '--help' and
>     'help' always generate identical output:

The intent is for '-h' and '--help' to provide global options and how
to get specific command help. A 'help' command should list the
available commands based on installed modules (and ultimately on
permissions?) and 'help command' should display detailed help on
'command'.

>       https://bugs.launchpad.net/keystone/+bug/936399

Heh. My past catches up with me. I've changed my mind here due to
the potentially long list of commands involved. Simple, obvious,
concise. Pick two. ;)

>  4. I think it would be good if the HIG gave guidelines on how the
>     help text should be formatted - in particular that positional
>     arguments are covered by the help text (e.g. keystone-manage does
>     not currently give any info on positional arguments required
>     until you specify too few).

That's a good idea. I'd propose that it be close to what we can get
out of argparse to minimise the amount of duplicated work.

Go ahead and start drafting in the wiki.

BTW, that page is in RST so it can be included in the source docs too.
I'm not happy with the formatting though.

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
<doug.hellmann@dreamhost.com> wrote:
> Running a cliff-based app without any arguments enters "interactive" mode
> (as of 0.4) which gives the user a new prompt and lets them run multiple
> commands before exiting. This is intended to be used as an optimization for
> commands to cache authentication credentials and clients and avoid logging
> in for every sub-command.

Dang dude, let us catch up!

> Do we need to specify this beyond saying that all subcommands must use
> argparse for argument parsing (the new framework depends on it anyway, and
> then they are all consistent)?

We should document that, I had just assumed it until now.

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Mon, Apr 30, 2012 at 2:56 PM, Dean Troyer <dtroyer@gmail.com> wrote:

> On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
> <doug.hellmann@dreamhost.com> wrote:
> > Running a cliff-based app without any arguments enters "interactive" mode
> > (as of 0.4) which gives the user a new prompt and lets them run multiple
> > commands before exiting. This is intended to be used as an optimization
> for
> > commands to cache authentication credentials and clients and avoid
> logging
> > in for every sub-command.
>
> Dang dude, let us catch up!
>

I had some spare time this weekend. :-)

FWIW, it's possible (likely) that the pull-request I sent last week that
got "list server" working doesn't work with the latest cliff. I haven't had
a chance to test, yet.


> > Do we need to specify this beyond saying that all subcommands must use
> > argparse for argument parsing (the new framework depends on it anyway,
> and
> > then they are all consistent)?
>
> We should document that, I had just assumed it until now.


Agreed.

Doug

On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
<doug.hellmann@dreamhost.com>wrote:

>
>
> On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@suse.com> wrote:
>
>> Dean Troyer (dtroyer@gmail.com) wrote:
>> > One of the first things to do is to find out who is interested in
>> > contributing to this project.and hopefully coordinating some of the
>> > work with the other emerging project-specific clients. Send me an
>> > email and I'll build a list to get the discussion started.
>>
>> Count me in - by 'build a list' do you mean a new mailing list?
>>
>> I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
>> (which looks like a great start on the topic!) and made some minor
>> tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I
>> wanted to make a few suggestions before I forget - can always continue
>> discussion elsewhere if appropriate:
>>
>> 1. Regarding "The subject names are always specified in command in
>> their singular form. This is contrary to natural language use."
>>
>> - I didn't understand the second sentence here, but shouldn't the
>> HIG should allow for scenarios where the verb can operate both on
>> individual objects and on multiple objects in batch?
>>
>
> I read that as meaning the command to list instances available to a tenant
> should be "list server" not the more natural "list servers".
>

I really hope that "list servers" would work.


>
> Can you give an example of a command that would work on multiple objects
> in batch?
>
>
>>
>> (Grammatical nitpick: if the verb is acting on the noun, then the
>> HIG should refer to the noun as "object" rather than "subject".)
>>
>> 2. I think it would be good if the HIG gave guidelines on how the
>> command should behave when run with no arguments.
>>
>
> Running a cliff-based app without any arguments enters "interactive" mode
> (as of 0.4) which gives the user a new prompt and lets them run multiple
> commands before exiting. This is intended to be used as an optimization for
> commands to cache authentication credentials and clients and avoid logging
> in for every sub-command.
>

One solution for this today is to use keystone's existing "token_get"
command, and then run subsequent commands with your specified token. So,
it's basically one request per command, instead of complete auth + request
per command.

$ keystone token-get
$ keystone --token=$TOKEN --endpoint=$ENDPOINT tenant-create [...]


>
> Since we're using argparse for the subcommands, the default behavior if a
> command is run without arguments depends on the subcommand. If the
> subcommand has no required arguments, it will do whatever it is meant to
> do. If it does require arguments and sees none, argparse prints an error
> message about whatever is missing (and possibly suggests that the user use
> --help to get instructions).
>
>
>>
>> 3. I think it would be good if the HIG recommended that, at least
>> when subcommands are permitted, single arguments '--help' and
>> 'help' always generate identical output:
>>
>> https://bugs.launchpad.net/keystone/+bug/936399
>> https://review.openstack.org/#/c/6460/
>
>
> The current version of cliff eats the --help option no matter where it
> appears on the command line, so to get help on a subcommand you always have
> to use "help" (without the dashes).
>
> $ openstack --help
> $ openstack list server --help
>
> both print the help for the "openstack" command, including a list of
> available subcommands
>
> $ openstack help list server
>
> prints the help for the "list server" subcommand of "openstack"
>

I find this behavior really annoying... --help should be contextual
(depending on whether a subcommand is present, and what it is).


>
>

>
>> 4. I think it would be good if the HIG gave guidelines on how the
>> help text should be formatted - in particular that positional
>> arguments are covered by the help text (e.g. keystone-manage does
>> not currently give any info on positional arguments required
>> until you specify too few).
>>
>
> Do we need to specify this beyond saying that all subcommands must use
> argparse for argument parsing (the new framework depends on it anyway, and
> then they are all consistent)?
>

I hope not... +1 for argparse.


>
>
>>
>> 5. I think it would be good if the HIG specified what sort of help
>> text should be included alongside error messages of (say) the
>> "you didn't give the right number of arguments" variety, and
>> whether the error message should appear before or after that help
>> text. My vote is after, because it's far easier for the human
>> eye to locate the end of a command's output than the beginning,
>> especially if the beginning has scrolled off the top of the
>> terminal.
>
>
>> Thanks,
>> Adam
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to : openstack@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help : https://help.launchpad.net/ListHelp
>>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help : https://help.launchpad.net/ListHelp
>
>

On Mon, Apr 30, 2012 at 3:19 PM, Dolph Mathews <dolph.mathews@gmail.com>wrote:

>
>
> On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann <
> doug.hellmann@dreamhost.com> wrote:
>
>>
>>
>> On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@suse.com> wrote:
>>
>>> Dean Troyer (dtroyer@gmail.com) wrote:
>>> > One of the first things to do is to find out who is interested in
>>> > contributing to this project.and hopefully coordinating some of the
>>> > work with the other emerging project-specific clients. Send me an
>>> > email and I'll build a list to get the discussion started.
>>>
>>> Count me in - by 'build a list' do you mean a new mailing list?
>>>
>>> I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
>>> (which looks like a great start on the topic!) and made some minor
>>> tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I
>>> wanted to make a few suggestions before I forget - can always continue
>>> discussion elsewhere if appropriate:
>>>
>>> 1. Regarding "The subject names are always specified in command in
>>> their singular form. This is contrary to natural language use."
>>>
>>> - I didn't understand the second sentence here, but shouldn't the
>>> HIG should allow for scenarios where the verb can operate both on
>>> individual objects and on multiple objects in batch?
>>>
>>
>> I read that as meaning the command to list instances available to a
>> tenant should be "list server" not the more natural "list servers".
>>
>
> I really hope that "list servers" would work.
>

I tend to agree, I was just explaining how I interpreted what was there.


>
>
>>
>> Can you give an example of a command that would work on multiple objects
>> in batch?
>>
>>
>>>
>>> (Grammatical nitpick: if the verb is acting on the noun, then the
>>> HIG should refer to the noun as "object" rather than "subject".)
>>>
>>> 2. I think it would be good if the HIG gave guidelines on how the
>>> command should behave when run with no arguments.
>>>
>>
>> Running a cliff-based app without any arguments enters "interactive" mode
>> (as of 0.4) which gives the user a new prompt and lets them run multiple
>> commands before exiting. This is intended to be used as an optimization for
>> commands to cache authentication credentials and clients and avoid logging
>> in for every sub-command.
>>
>
> One solution for this today is to use keystone's existing "token_get"
> command, and then run subsequent commands with your specified token. So,
> it's basically one request per command, instead of complete auth + request
> per command.
>
> $ keystone token-get
> $ keystone --token=$TOKEN --endpoint=$ENDPOINT tenant-create [...]
>

That sounds sort of like the way ssh-agent works, and I like that as an
optimization, too.


> Since we're using argparse for the subcommands, the default behavior if a
>> command is run without arguments depends on the subcommand. If the
>> subcommand has no required arguments, it will do whatever it is meant to
>> do. If it does require arguments and sees none, argparse prints an error
>> message about whatever is missing (and possibly suggests that the user use
>> --help to get instructions).
>>
>>
>>>
>>> 3. I think it would be good if the HIG recommended that, at least
>>> when subcommands are permitted, single arguments '--help' and
>>> 'help' always generate identical output:
>>>
>>> https://bugs.launchpad.net/keystone/+bug/936399
>>> https://review.openstack.org/#/c/6460/
>>
>>
>> The current version of cliff eats the --help option no matter where it
>> appears on the command line, so to get help on a subcommand you always have
>> to use "help" (without the dashes).
>>
>> $ openstack --help
>> $ openstack list server --help
>>
>> both print the help for the "openstack" command, including a list of
>> available subcommands
>>
>> $ openstack help list server
>>
>> prints the help for the "list server" subcommand of "openstack"
>>
>
> I find this behavior really annoying... --help should be contextual
> (depending on whether a subcommand is present, and what it is).
>

That's how it worked originally. When I got the pull-request from Dean I
assumed it was intended to follow some existing standard.

>From an implementation perspective, it was challenging to use two levels of
argparse parsers to have the --help option applied separately, so I had the
main app using optparse configured to stop at the first positional argument
(value without a "-" at the front). That was a little ugly, since it
depended on a deprecated module. I was not able to find a way to do exactly
the same thing in argparse without adding some of my own logic on top.


> 4. I think it would be good if the HIG gave guidelines on how the
>>> help text should be formatted - in particular that positional
>>> arguments are covered by the help text (e.g. keystone-manage does
>>> not currently give any info on positional arguments required
>>> until you specify too few).
>>>
>>
>> Do we need to specify this beyond saying that all subcommands must use
>> argparse for argument parsing (the new framework depends on it anyway, and
>> then they are all consistent)?
>>
>
> I hope not... +1 for argparse.
>
>
>>
>>
>>>
>>> 5. I think it would be good if the HIG specified what sort of help
>>> text should be included alongside error messages of (say) the
>>> "you didn't give the right number of arguments" variety, and
>>> whether the error message should appear before or after that help
>>> text. My vote is after, because it's far easier for the human
>>> eye to locate the end of a command's output than the beginning,
>>> especially if the beginning has scrolled off the top of the
>>> terminal.
>>
>>
>>> Thanks,
>>> Adam
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to : openstack@lists.launchpad.net
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help : https://help.launchpad.net/ListHelp
>>>
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to : openstack@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help : https://help.launchpad.net/ListHelp
>>
>>
>

On Mon, Apr 30, 2012 at 2:19 PM, Dolph Mathews <dolph.mathews@gmail.com> wrote:
> I find this behavior really annoying... --help should be contextual
> (depending on whether a subcommand is present, and what it is).

> I hope not... +1 for argparse.

Actually, argparse is one reason for this behaviour. It doesn't like
duplicated options in subparsers, nor subsets of names like we found
in keystone with --tenant and --tenant_id, etc. IIRC none of the
existing clients do that, they all rely on 'help command' to get
command-specific help.

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Mon, Apr 30, 2012 at 3:27 PM, Dean Troyer <dtroyer@gmail.com> wrote:

> On Mon, Apr 30, 2012 at 2:19 PM, Dolph Mathews <dolph.mathews@gmail.com>
> wrote:
> > I find this behavior really annoying... --help should be contextual
> > (depending on whether a subcommand is present, and what it is).
>
> > I hope not... +1 for argparse.
>
> Actually, argparse is one reason for this behaviour. It doesn't like
> duplicated options in subparsers, nor subsets of names like we found
> in keystone with --tenant and --tenant_id, etc. IIRC none of the
> existing clients do that, they all rely on 'help command' to get
> command-specific help.


Duplicated options will be less of an issue with cliff, since the second
level parser isn't instantiated until after the options to the main program
have already been consumed.

Matt Joyce (matt@nycresistor.com) wrote:
> >  3. I think it would be good if the HIG recommended that, at least
> >     when subcommands are permitted, single arguments '--help' and
> >     'help' always generate identical output:
> >
> >       https://bugs.launchpad.net/keystone/+bug/936399
> >       https://review.openstack.org/#/c/6460/
>
> Same for Version ( --version )

Good point! I've added some draft text to the wiki page for that,
partially pinched from:

http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces

As you can see, the GNU standards go into great detail regarding
--version; I don't know if we want to be as stringent, particularly
regarding copyright / license notices, but there's some good food for
thought there.

> >  5. I think it would be good if the HIG specified what sort of help
> >     text should be included alongside error messages of (say) the
> >     "you didn't give the right number of arguments" variety, and
> >     whether the error message should appear before or after that help
> >     text.  My vote is after, because it's far easier for the human
> >     eye to locate the end of a command's output than the beginning,
> >     especially if the beginning has scrolled off the top of the
> >     terminal.
>
> I wonder if this event tracking is relevant to metering. At the very
> least it could be relevant to an audit log / revision history.
>
> Curious if that's outside the scope of the CLI. For one, I believe
> it would be worthwhile to be able to integrate with the APIs to
> provide a recall of past events and results.

Agreed - while server-side auditing is a more important component than
client-side, having both sounds potentially useful to me too. And
while it's outside the scope of a CLI HIG discussion, it's
nevertheless relevant to any work on a unified CLI.

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

Doug Hellmann (doug.hellmann@dreamhost.com) wrote:
> On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@suse.com> wrote:
>
> > Dean Troyer (dtroyer@gmail.com) wrote:
> > > One of the first things to do is to find out who is interested in
> > > contributing to this project.and hopefully coordinating some of the
> > > work with the other emerging project-specific clients. Send me an
> > > email and I'll build a list to get the discussion started.
> >
> > Count me in - by 'build a list' do you mean a new mailing list?
> >
> > I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
> > (which looks like a great start on the topic!) and made some minor
> > tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I
> > wanted to make a few suggestions before I forget - can always continue
> > discussion elsewhere if appropriate:
> >
> > 1. Regarding "The subject names are always specified in command in
> > their singular form. This is contrary to natural language use."
> >
> > - I didn't understand the second sentence here, but shouldn't the
> > HIG should allow for scenarios where the verb can operate both on
> > individual objects and on multiple objects in batch?
>
> I read that as meaning the command to list instances available to a tenant
> should be "list server" not the more natural "list servers".

Ah I see - makes sense now, thanks.

> Can you give an example of a command that would work on multiple objects in
> batch?

Things like

openstack set hosts --name-matches='foo*' --maintenance enable

# use with caution! would require confirmation prompt
openstack delete images --name-matches='bar*'

?

> Running a cliff-based app without any arguments enters "interactive" mode
> (as of 0.4) which gives the user a new prompt and lets them run multiple
> commands before exiting. This is intended to be used as an optimization for
> commands to cache authentication credentials and clients and avoid logging
> in for every sub-command.

I love it :-) I guess it has readline support and could also offer
completion too?

Forgive the newbie question, but does cliff have significantly
different goals or scope to cement? I attended the Quantum CLI
rewrite session at the summit:

http://folsomdesignsummit2012.sched.org/event/b20c2743ac6ab35d4f33b4fcd1da4fa7

and IIRC they were going to move to using cement. The notes from that
session start on line 224 of:

http://etherpad.openstack.org/quantum-folsom

In particular note: "Need to do some cleanup before the One CLI to
Rule Them All project is going to be far enough long to be usable for
Quantum commands". I wasn't sure how the work with cement would
dovetail with this project though.

> Since we're using argparse for the subcommands, the default behavior if a
> command is run without arguments depends on the subcommand. If the
> subcommand has no required arguments, it will do whatever it is meant to
> do. If it does require arguments and sees none, argparse prints an error
> message about whatever is missing

Agreed, except ...

> (and possibly suggests that the user use --help to get
> instructions).

One of my pet peeves is commands which tell you that you screwed up
but don't immediately offer help so you can take appropriate remedial
action. In other words, bearing in mind Dean's section on
"User-Centered Design" in the HIG, I'd prefer a command outputted
usage text along with an error than one or two sentences forcing you
to rerun the command with the --help option.

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Tue, May 1, 2012 at 12:54 PM, Adam Spiers <aspiers@suse.com> wrote:
> Agreed - while server-side auditing is a more important component than
> client-side, having both sounds potentially useful to me too.  And
> while it's outside the scope of a CLI HIG discussion, it's
> nevertheless relevant to any work on a unified CLI.

Sounds like a blueprint waiting to be written... ;)

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

Doug Hellmann (doug.hellmann@dreamhost.com) wrote:
> On Mon, Apr 30, 2012 at 2:56 PM, Dean Troyer <dtroyer@gmail.com> wrote:
> > On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
> > <doug.hellmann@dreamhost.com> wrote:
> > > Do we need to specify this beyond saying that all subcommands must use
> > > argparse for argument parsing (the new framework depends on it anyway, and
> > > then they are all consistent)?
> >
> > We should document that, I had just assumed it until now.
>
> Agreed.

Sorry, that made me think of another newbie question - is the
intention that all actions (including user- / site- / vendor-specific
extensions) *must* be implemented in Python using the client API
modules? Or will it also be able to support extensions simply by
dropping arbitrary openstack-ACTION executables on $PATH? I like the
way git lets you do the latter, e.g. I have a bunch of shell scripts
named git-something in my own ~/bin which help me extend git and
automate my git workflows, and they can still be invoked via `git
something'. In case you're curious, here they are ...

https://github.com/aspiers/git-config#readme

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Tue, May 1, 2012 at 1:49 PM, Adam Spiers <aspiers@suse.com> wrote:
> Sorry, that made me think of another newbie question - is the
> intention that all actions (including user- / site- / vendor-specific
> extensions) *must* be implemented in Python using the client API
> modules?  Or will it also be able to support extensions simply by
> dropping arbitrary openstack-ACTION executables on $PATH?  I like the
> way git lets you do the latter, e.g. I have a bunch of shell scripts

At this point we have only talked about extending the client via
cliff-derived plugins. I'm trying to decide what the value add of
arbitrary binaries being called is; the way I imagine it the binary
would have to duplicate the token flow auth at a minimum, why not just
call it directly? git has the advantage here of keeping its state in
the filesystem. What little state we have is in memory.

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

Dean Troyer (dtroyer@gmail.com) wrote:
> On Mon, Apr 30, 2012 at 2:19 PM, Dolph Mathews <dolph.mathews@gmail.com> wrote:
> > I find this behavior really annoying... --help should be contextual
> > (depending on whether a subcommand is present, and what it is).
>
> > I hope not... +1 for argparse.
>
> Actually, argparse is one reason for this behaviour. It doesn't like
> duplicated options in subparsers, nor subsets of names like we found
> in keystone with --tenant and --tenant_id, etc. IIRC none of the
> existing clients do that, they all rely on 'help command' to get
> command-specific help.

As of my recent patch, --help is contextual in nova:

https://review.openstack.org/6460

and I have started work on some of the other commands too, so it would
be helpful if we could reach a consensus on this soon ... although
please let me know if I am wasting my time working on other commands
due to any imminent rewrites using python-openstack!

I agree with Dolph - there is a precedent from other well-known
programs (git, hg, svn are the first ones I can think of) for --help
to behave differently depending on whether or not it was preceded by a
subcommand. So my vote is that we should definitely aim to adhere to
this pattern.

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Tue, May 1, 2012 at 1:54 PM, Adam Spiers <aspiers@suse.com> wrote:

> Matt Joyce (matt@nycresistor.com) wrote:
> > > 3. I think it would be good if the HIG recommended that, at least
> > > when subcommands are permitted, single arguments '--help' and
> > > 'help' always generate identical output:
> > >
> > > https://bugs.launchpad.net/keystone/+bug/936399
> > > https://review.openstack.org/#/c/6460/
> >
> > Same for Version ( --version )
>
> Good point! I've added some draft text to the wiki page for that,
> partially pinched from:
>
>
> http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces
>
> As you can see, the GNU standards go into great detail regarding
> --version; I don't know if we want to be as stringent, particularly
> regarding copyright / license notices, but there's some good food for
> thought there.
>

The version flag is also handled by argparse automatically. We can set the
version string to whatever we want, of course.


>
> > > 5. I think it would be good if the HIG specified what sort of help
> > > text should be included alongside error messages of (say) the
> > > "you didn't give the right number of arguments" variety, and
> > > whether the error message should appear before or after that help
> > > text. My vote is after, because it's far easier for the human
> > > eye to locate the end of a command's output than the beginning,
> > > especially if the beginning has scrolled off the top of the
> > > terminal.
> >
> > I wonder if this event tracking is relevant to metering. At the very
> > least it could be relevant to an audit log / revision history.
> >
> > Curious if that's outside the scope of the CLI. For one, I believe
> > it would be worthwhile to be able to integrate with the APIs to
> > provide a recall of past events and results.
>
> Agreed - while server-side auditing is a more important component than
> client-side, having both sounds potentially useful to me too. And
> while it's outside the scope of a CLI HIG discussion, it's
> nevertheless relevant to any work on a unified CLI.
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to : openstack@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help : https://help.launchpad.net/ListHelp
>

On Tue, May 1, 2012 at 2:11 PM, Adam Spiers <aspiers@suse.com> wrote:
> As of my recent patch, --help is contextual in nova:

I hadn't seen that yet...

> and I have started work on some of the other commands too, so it would
> be helpful if we could reach a consensus on this soon ... although
> please let me know if I am wasting my time working on other commands
> due to any imminent rewrites using python-openstack!

The continued existence of the project-specific commands is really up
to the projects themselves. I think it would be great to converge
them on things like this, but trying to get them all to work the same
is what led us to openstackclient due to backward compatibility and
all. My guess would be that the existing client binaries would live
through the 'G' release even if we decided to deprecate them now.

> I agree with Dolph - there is a precedent from other well-known
> programs (git, hg, svn are the first ones I can think of) for --help
> to behave differently depending on whether or not it was preceded by a
> subcommand.  So my vote is that we should definitely aim to adhere to
> this pattern.

How about detailing it in the HIG and once we get a command or two
implemented with argument parsing we give it a shot?

dt

--

Dean Troyer
dtroyer@gmail.com

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

On Tue, May 1, 2012 at 11:49 AM, Adam Spiers <aspiers@suse.com> wrote:
> Doug Hellmann (doug.hellmann@dreamhost.com) wrote:
>> On Mon, Apr 30, 2012 at 2:56 PM, Dean Troyer <dtroyer@gmail.com> wrote:
>> > On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
>> > <doug.hellmann@dreamhost.com> wrote:
>> > > Do we need to specify this beyond saying that all subcommands must use
>> > > argparse for argument parsing (the new framework depends on it anyway, and
>> > > then they are all consistent)?
>> >
>> > We should document that, I had just assumed it until now.
>>
>> Agreed.
>
> Sorry, that made me think of another newbie question - is the
> intention that all actions (including user- / site- / vendor-specific
> extensions) *must* be implemented in Python using the client API
> modules?  Or will it also be able to support extensions simply by
> dropping arbitrary openstack-ACTION executables on $PATH?  I like the
> way git lets you do the latter, e.g. I have a bunch of shell scripts
> named git-something in my own ~/bin which help me extend git and
> automate my git workflows, and they can still be invoked via `git
> something'.  In case you're curious, here they are ...
>

That made me think of something. Is the intention for the client to
be portable?

Defining portable as :

Easily deployed to a host
Minimal dependency set
Cross operating system portability ( pipe dream but python is solid at it )

Strikes me that having the package end up being portable would be a
huge boon to openstack.

-Matt

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp