CLI built-in help is really confusing and inconsistent (examples: user addrole, db create, etc.)

0 views

CLIbug-report

Skip to first unread message

Andrew Simms

unread,

Oct 22, 2013, 5:00:02 PM10/22/13

to sta...@clarkparsia.com

Consider the built-in help for addrole:

stardog-admin [--server <server url>] user addrole

(-R <role> | --role <role>) [(-u <username> | --username <username>)]

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

addrole

Assigns a role to a user.

With --role option, Role to be associated with the user.

With --username option, User name.

With --passwd option, Password.

With --ask-password option, Prompt for password.

This command has a mandatory argument, which is not mentioned: the user name you are trying to add:

stardog-admin [--server <server url>] user addrole name

(-R <role> | --role <role>) [(-u <username> | --username <username>)]

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

Another inconsistency is with db create:

stardog-admin [--server <server url>] db create

[(-c <config> | --config <config>)]

[(-o <options> | --options <options>)...] [(-t <type> | --type <type>)]

[(-n <name> | --name <name>)] [(-s | --searchable)] [(-d | --durable)]

[(-i | --index-triples-only)] [(-u <username> | --username <username>)]

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

Specifying a name is required, yet it is shown as optional. More clear (and consistent) would be:

stardog-admin [--server <server url>] db create databasename

[(-c <config> | --config <config>)]

[(-o <options> | --options <options>)...] [(-t <type> | --type <type>)]

[(-s | --searchable)] [(-d | --durable)]

[(-i | --index-triples-only)] [(-u <username> | --username <username>)]

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

Also, this appears in help text many commands:

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

It should be written (you should either specify the password or have the system prompt for it):

[(-p <password> | --passwd <password> | -P | --ask-password)]

Mike Grove

unread,

Oct 23, 2013, 9:10:08 AM10/23/13

to stardog

On Tue, Oct 22, 2013 at 5:00 PM, Andrew Simms <ams...@gmail.com> wrote:

Consider the built-in help for addrole:

stardog-admin [--server <server url>] user addrole
(-R <role> | --role <role>) [(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

addrole
Assigns a role to a user.

With --role option, Role to be associated with the user.

With --username option, User name.

With --passwd option, Password.

With --ask-password option, Prompt for password.

This command has a mandatory argument, which is not mentioned: the user name you are trying to add:

stardog-admin [--server <server url>] user addrole name
(-R <role> | --role <role>) [(-u <username> | --username <username>)]

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

I think you snipped the help prematurely, this is what stardog-admin help user addrole displays as it's full synopsis:

stardog-admin [--server <server url>] user addrole

[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

(-R <role> | --role <role>) [(-u <username> | --username <username>)]

[--] <username>

The mandatory argument, username, is listed after all of the command options. While it's perhaps not ideal that it's listed at the end, arguments in the help are shown in that order because you cannot put any of the command arguments, such as --role, after the mandatory username argument because it is expected to be the final argument of the program.

Another inconsistency is with db create:

stardog-admin [--server <server url>] db create
[(-c <config> | --config <config>)]
[(-o <options> | --options <options>)...] [(-t <type> | --type <type>)]
[(-n <name> | --name <name>)] [(-s | --searchable)] [(-d | --durable)]

[(-i | --index-triples-only)] [(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

Specifying a name is required, yet it is shown as optional. More clear (and consistent) would be:

stardog-admin [--server <server url>] db create databasename

[(-c <config> | --config <config>)]
[(-o <options> | --options <options>)...] [(-t <type> | --type <type>)]
[(-s | --searchable)] [(-d | --durable)]

[(-i | --index-triples-only)] [(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

The database name via -n/--name is not actually required, which is why it's shown as optional. You can specify it in your configuration (-c/--config), in which case, you don't need to provide a value for the name argument. The help for the name argument mentions this quirk: "The name is a required property of a database, but it can be omitted on the command line if it is specified in a configuration file via the -c/--config flag."

Cheers,

Mike

Also, this appears in help text many commands:
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

It should be written (you should either specify the password or have the system prompt for it):
[(-p <password> | --passwd <password> | -P | --ask-password)]

--
-- --
You received this message because you are subscribed to the C&P "Stardog" group.
To post to this group, send email to sta...@clarkparsia.com
To unsubscribe from this group, send email to
stardog+u...@clarkparsia.com
For more options, visit this group at
http://groups.google.com/a/clarkparsia.com/group/stardog?hl=en

andrew...@multiscalehn.com

unread,

Oct 23, 2013, 11:24:55 AM10/23/13

to sta...@clarkparsia.com

Thanks for the clarification on database name, I had forgotten about using a config file.

However, in my stardog-admin user help text, the additional line you mention is not there anywhere in my output:

[--] <username>

stardog@triple4:/localstore/stardog/stardog-2.0.1$ bin/stardog-admin help user
NAME
        stardog-admin user - Commands for working with users

SYNOPSIS
        stardog-admin [--server <server url>] user add [(-s | --superuser)]
                [(-N <password> | --new-password <password>)]

stardog-admin [--server <server url>] user disable

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user enable

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user grant
(-a <action> | --action <action>) (-o <object> | --object <object>)

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user list [--verbose]
[(-f <format> | --format <format>)]

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user passwd
[(-N <new password> | --new-password <new password>)]

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user permission
[(-f <format> | --format <format>)]

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user remove

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user removerole

(-R <role> | --role <role>) [(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

stardog-admin [--server <server url>] user revoke
(-a <action> | --action <action>) (-o <object> | --object <object>)

[(-u <username> | --username <username>)]
[(-p <password> | --passwd <password>)] [(-P | --ask-password)]

OPTIONS
        --server <server url>
            URL of Stardog Server. If this option isn't specified, it will be
            read from JVM argument 'stardog.default.cli.server'. If the JVM arg
            isn't set, the default value 'snarl://localhost:5820' is used. If
            server URL has no explicit port value, the default port value '5820'
            is used. Example: 'stardog --server snarl://12.34.56.78:5820 server
            stop'

COMMANDS
        add
            Adds a new user.

            With --superuser option, Superuser flag. If this flag is set, the
            new user will be a super user.

            With --new-password option, Password for new user. If not provided,
            the user will be prompted to enter it.