Create CLI steering guidelines

[leggetter]

What are the main motivations for the CLI? Who is it for? How should it be used?

Some background: We decided to create the CLI so that we could more quickly (in a few commands) get to the point where we could start building (writing code) Voice API v2 functionality.

We then realised that a CLI is just really handy. We can perform quick number lookups (insight), buy numbers, check account balance etc. Others at Nexmo are also finding it really useful e.g. support and sales engineers.

I think we should be able to create a few bullet points that help us guide the decisions we make about the CLI.

[cbetta]

@leggetter good idea. Do you have an idea how to start this?

I also think that based on this we could look at the next API and see what's missing in the CLI, and then map out what we think (based on these guidelines) should be added to the CLI next.

[tjlytle]

Feels to me like the CLI should:

• provide a CLI to the API (basically proxy the client library)
  • namespaces are mirrored
  • arguments match
• provide a higher level interface to common processes
  • internally are just a series of API calls
  • interactively describe what information is needed / suggest defaults

Not sure if that's exactly what @leggetter is looking for, but perhaps helpful.

[cbetta]

I am not sure I agree with this. As @sammachin already pointed out somewhere else: the CLI is more of a UI than anything else. It's an alternative to the dashboard.

By limiting the CLI to what's possible in the API we're limiting the usability of the CLI. There's already some interesting stuff in the CLI that would be hard to do if it was just a 1:1 match to the API.

[tjlytle]

Sorry, those were two separate things. So provide a basic CLI to the API (essentially replace curl, when I just want to make a one off API call / potentially script some activity in the shell). This is the 1:1 mirror, and potentially something that can be generated from a solid API spec.

Then the second "provide a higher level interface to common processes" is (I think) exactly what @sammachin and @cbetta are talking about.

I think those are two major use cases, and it makes sense to support both (since the latter will essentially consume the former). But certainly not arguing it should be limited to single API calls, rather the opposite.

[cbetta]

Ah cool, good to see we agree on not limiting it to a 1:1 map.

I initially agreed with you that getting the 1:1 mirror in there at the least but as I was writing this I was starting to feel this might not be the wisest idea.

Many of the API endpoints take a lot of different params in different combos, which would have to be mapped to optional flags. This would make the CLI bulky and complicated very quickly. The CLI in the end is a UI on top of the API and when we're building a UI it is totally worth it trying to give the user the best UX.

I definitely thing it makes sense to look at mapping as much of the functionality from the API into the CLI but we should do so in a way that makes it as easy as possible for users to do things fast, with shortcuts build in from the start to make calls easier.

A good example is https://github.com/Nexmo/nexmo-cli/pull/78 .

The SMS endpoint supports a lot of things: vcard, vcal, different types of messages, etc. But a good starting point was to just be able to send an SMS. I then added a shortcut where you don't actually need to specify the from unless you want. I made this guess based on the fact that one of the core users at the moment are the dev advocates who need to quickly be able to show how Nexmo works, but obviously it would be good to plan out other user's needs too.

[tjlytle]

I think 1:1 mirror would be a future goal (but important to note its usefulness now) as some in-progress unification of the API should make that a far simpler process.

But if we do put that down to support in the future, it may be advantageous at this point to somehow distinguish between CLI commands that match the API directly, and those that are higher level (assemble multiple calls).

[cbetta]

@tjlytle how do you imaging we distinguish? I imagine we could move all 1:1 under the api namespace.

E.g. nexmo api:account:get-balance vs nexmo balance

[sammachin]

We did have a debate about what features should be added to the CLI early on, specifically things like sending an SMS or Verify.

IIRC We decided that the CLI should be a tool for managing your account settings not for actual traffic events, personally I still stand by that. Things like sending a message should be done with curl or httpie.

[lornajane]

See https://github.com/nexmo/cli-standards for the current working standards