Clarifying CLI flags

[L Tratt]

At the moment if you do npx skdb --help (or just npx skdb) you get this help string:

Usage: node_modules/.bin/skdb-cli [--help]
    [--db <db>]  -- Name of database to connect to.
    [--host <host>]  -- URI to connect to. Default: wss://api.skiplabs.io
    [--access-key <key>]  -- Access key to use. Default: first specified in credentials file.
    [--dev]  -- Connect to the local dev server, use this to access credentials.
    [--json-output]  -- Rows are output as JSON objects. Default: false.
    [--pipe-separated-output]  -- SQL output is separated by a pipe. Default: false.
    [--simple-output]  -- No cute terminal usage. E.g. no readline.
    [--add-cred]  -- Add a credential to /home/user/.skdb/credentials. Pass the private key b64 on stdin.
    [--create-db <db>]  -- Create database.
    [--create-user]  -- Create user.
    [--remote-repl]  -- Interactively execute SQL queries against the server.
    [--local-repl]  -- Interactively execute SQL queries against a local db.
    [--schema]  -- Dump the database schema as SQL DML.
    [--table-schema <table>]  -- Dump the table schema as SQL DML.
    [--view-schema <view>]  -- Dump the view schema as SQL DML.

Anything passed on stdin will be evaluated as sql by the remote db.

It's a bit difficult from this to work out exactly what combinations of flags are valid. For example consider --create-user:

$ npx skdb --create-user
# prints out the same help string as earlier
$ npx skdb --create-user --dev
# prints out the same help string as earlier
$ npx skdb --create-user --db chat-app
Could not find credentials for chat-app in /home/user/.skdb/credentials
$ npx skdb --create-user --dev --db chat-app
# Creates a user!

The eventual sequence of flags does make sense, but it's hard to guess from the string. I wonder if we can make a more helpful help string? I'm not sure exactly what all the valid combinations are, but I think it's something like:

[--dev | --host <host> --access-key <key>]
[--json-output | --pipe-separated-output | --simple-output]
--add-cred | --create-db <db> | --create-user | --remote-repl | --local-repl | --schema | --table-schema <table> | --view-schema <view>

Warning: I might have got the combinations very wrong!

[Josh Berdine]

I agree that such a format for the usage help would be good. I think the thing to do is read the code in sql/ts/src/skdb-cli.ts following the call to parseArgs and construct the constraints from that.

[L Tratt]

I'm not quite sure what the *-output flags do, at least with --create-user:

$ npx skdb --dev --create-user --db chat-app
Successfully created user:  {
  f7rXW0KTJrjfjya0cCRZNFZ3Ht3: '...'
}
$ npx skdb --dev --create-user --db chat-app --json-output
Successfully created user:  {
  'f7sAj2vsTNMagAAFUSig-HYMNb7': '...'
}
$ npx skdb --dev --create-user --db chat-app --pipe-separate
ed-output
Successfully created user:  {
  f7sAluP0KxiKRBiah_sI_cMj_j3: '...'
}
$ npx skdb --dev --create-user --db chat-app --pipe-separate
Successfully created user:  {
  f7sAw_b2on9Rcw_GyVinHqvcRu4: '...'
}

Ideally one of those would give me output which can be automatically slurped into other tools (e.g. as JSON, or by spitting out two lines etc).

[L Tratt]

One thing that I've only just noted is that the formatting of the output of --create-user has inconsistent quoting. Note in the above:

  'f7sAj2vsTNMagAAFUSig-HYMNb7': '...'

vs.:

  f7sAluP0KxiKRBiah_sI_cMj_j3: '...'

The former access key / user ID is quoted (because, I think, of the presence of -), the latter isn't. I would suggest always quoting this output if possible.

[Greg Sexton]

It's because it's printed as a js object.