[almighty] CLI Documentation

[Max Rydahl Andersen]

On 15 Aug 2016, at 8:35, Thomas Mäder wrote:

> Hi folks,
>
> It has been requested that we document our command line interface. To 
> me, however it's not quite clear in what form we should do that: 
> technically, the cli is self-documenting. If you do "alm-cli --help", 
> it will give you a list of possible commands and options. The alm-cli 
> command is mentioned in the developer set up section on github. Do we 
> believe this is sufficient? What else is necessary?

The issue we got open is that the docs don't actually explain to you 
*how* to use it.

What I current see when running `alm-cli create --help` that does not 
actually tell me how to run this unless we expect users to know the json 
format.

```
./bin/alm-cli create workitem --help                                     
                                                                                                                             ◼
Payload example:

{
    "fields": {
       "Maiores similique facere ipsa.": 0.7636827460427832
    },
    "name": "Dicta numquam aut.",
    "type": "Expedita minima."
}

Usage:
   alm-cli create workitem ["/api/workitem"] [flags]

Flags:
       --content string   Request content type override, e.g. 
'application/x-www-form-urlencoded'
       --payload string   Request body encoded in JSON
       --pp               Pretty print response body

Global Flags:
       --dump               Dump HTTP request and response.
       --format string      Format used to create auth header or query 
from key (default "Bearer %s")
   -H, --host string        API hostname (default "almighty.io")
       --key string         API key used for authentication
   -s, --scheme string      Set the requests scheme
   -t, --timeout duration   Set the request timeout (default 20s)
```

So if I follow this I run:

```./bin/alm-cli create workitem --payload "{ "fields": { "Maiores 
similique facere ipsa.": 0.7636827460427832 }, "name": "Dicta numquam 
aut.", "type": "Expedita minima." }"
```

```
Error: failed to deserialize payload: invalid character 'f' looking for 
beginning of object key string
Usage:
   alm-cli create workitem ["/api/workitem"] [flags]

Flags:
       --content string   Request content type override, e.g. 
'application/x-www-form-urlencoded'
       --payload string   Request body encoded in JSON
       --pp               Pretty print response body

Global Flags:
       --dump               Dump HTTP request and response.
       --format string      Format used to create auth header or query 
from key (default "Bearer %s")
   -H, --host string        API hostname (default "almighty.io")
       --key string         API key used for authentication
   -s, --scheme string      Set the requests scheme
   -t, --timeout duration   Set the request timeout (default 20s)

failed to deserialize payload: invalid character 'f' looking for 
beginning of object key string%```

And thus I'm still not closer being able to run the cli as a new user.

Would be good we actually have a *working* example in the cli help 
output, or as minimum when we actually close of an issue for cli adds an 
example that can be run and then used for testing/verifying/playing with 
the cli.

/max
http://about.me/maxandersen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/almighty-public/attachments/20160816/59e2f412/attachment.htm>