
Docli – A declarative language for command-line interfaces in Go - celicoo
https://docli.dev
======
sametmax
I used to love doctopt, but with usage your realise:

\- i18n is made hard

\- syntax errors are not caught by tooling

\- you don't get automatic args checking or env var override

Eventually, a well made programmative API is better.

~~~
coldtea
> _\- i18n is made hard_

It's also mostly redundant. I'd expect CLI users to be able to parse flags and
--help messages in english.

And I'm not saying it as a native english speaker -- which I'm not. Without
english knowledge you can't parse 99% of existing, never to be i18n standard
UNIX commands, flags, and manpages.

~~~
thayne
> Without english knowledge you can't parse 99% of existing, never to be i18n
> standard UNIX commands, flags, and manpages.

That makes me sad.

~~~
coldtea
That makes me happy. I'm all for national languages, ethnic nuances etc (I'm
not English-native-speaker myself), great spell checkers, voice recognition,
fonts, etc for all languages.

But for text work (writing, reading, etc).

Not on my fucking programming languages (like bizarro foreign variable names
in source code), and ideally, not on my CLI either.

Let's have a common universal language in our domain.

Doctors get to use latin names and common terms for tons of medical staff
whatever their country. Pilots get to speak english with every control tower
all around the world.

Computer work should have some of that too.

~~~
thayne
There's a difference between having source code and CLI commands in a hodge-
podge of languages and not having translations of man pages.

------
hwj
This is a Go library that parses a usage string into an AST.

~~~
umvi
"Docli" makes it sound like a generic documentation generator for CLIs.

IMO name should make it clear it is Go-only. Something like "GoastArgs: a Go
library that parses a usage string/CLI args into an AST"

~~~
celicoo
Thanks for the feedback umvi. I will be working on making it clear that Docli
is a Go library.

~~~
dromedary512
But, for the love of God, please don't put the word "Go" in the name :D

------
ilovecaching
I still feel that cobra and docopt are ungoish despite the author of cobra
getting hired on. There's simply too much magic to both of them. I would much
rather they improve flags, which is what I use. It really doesn't take that
much with flags to add subcommands, etc, but it could be made better.

~~~
rajangdavis
Can you elaborate on what makes cobra ungoish? I had built a CLI using it
without prior knowledge of Go (but with a background in scripting languages
and a some C#) and it seemed pretty straightforward.

The only issue that I can tell was that you can possibly create errors that
the compiler can miss, but it's been pretty solid otherwise.

~~~
ilovecaching
Cobra is very much a kitchen sink approach with a lot of gen. I'd rather have
less dependency and write just using the stdlib without the kitchen sink,
which is more goish.

~~~
rajangdavis
That makes a lot of sense.

I guess the parallel for me would be using Rack as opposed to Rails for Ruby.

Thanks for responding!

------
deforciant
For servers I prefer using:
[https://github.com/alecthomas/kingpin](https://github.com/alecthomas/kingpin),
allows you to really nicely expand based on main arguments with flags. Also,
setting defaults is a joy.

For CLIs - [https://github.com/spf13/cobra](https://github.com/spf13/cobra).

However, will definitely try out Docli whenever I start building something new
:)

------
thanatos_dem
Seems like Cobra is pretty well established in this space -
[https://github.com/spf13/cobra](https://github.com/spf13/cobra)

Tho admittedly it works in reverse; it generates the doc/help info rather than
parsing it into an AST. It addresses the “boilerplate” issue with code gen as
well, but it has a CLI to generate code that’s pretty powerful.

For instance, how does docli handle subcommands? How about global vs command
specific flags? For any case beyond the basic single command CLI, it seems
like there would need to be all sorts of magic and non-obvious formatting
requirements on the doc string.

~~~
celicoo
Hey! I've opened an issue to discuss about the subcommands feature:
[https://github.com/celicoo/docli/issues/10](https://github.com/celicoo/docli/issues/10)

I would love to know your opinion about it.

------
matt-attack
Anyone have a recommendation for Node.js? I've been extremely frustrated with
commander [1].

[1]
[https://www.npmjs.com/package/commander](https://www.npmjs.com/package/commander)

~~~
Kamshak
Try oclif [https://github.com/oclif/oclif](https://github.com/oclif/oclif)

~~~
curry-castaway
I can second this recommendation – Oclif[0] is an absolute pleasure to use.
I'd even encourage developers who aren't at a "full-stack Node.js shop" to
give it a shot.

I'm particularly impressed with the bash and zsh autocomplete support. I was
delighted when I finished setting it up and everything worked perfectly on the
first try.

[0]: [https://oclif.io/](https://oclif.io/)

------
calebwin
I really like that graphic for the website and README! Did you make it?

~~~
celicoo
Thanks! It was a friend of mine. You can see more of his work at
[https://www.instagram.com/sutocreation](https://www.instagram.com/sutocreation)

------
maxaf
Prior art: [http://docopt.org/](http://docopt.org/)

~~~
rb808
[https://picocli.info/](https://picocli.info/) for java

~~~
tamasnet
This looks awesome, thanks for mentioning it!

------
CamouflagedKiwi
Not really a fan of this approach. I don't like the duality between the help
text and the struct it gets bound to - much prefer the approach of generating
the help text from a struct.

[https://github.com/jessevdk/go-flags](https://github.com/jessevdk/go-flags)
is my favourite option; it's lightweight but amazingly featureful, and I much
prefer the declarative approach to a programmatic one like the standard
library flags package

------
pushpop
Their example here confuse me:

[https://github.com/celicoo/docli/blob/master/examples/terraf...](https://github.com/celicoo/docli/blob/master/examples/terraform/main.go)

`workspace` isn't a boolean flag. So it isn't clear from that example how - or
even if - docli can work with more complex conditional arguments.

Is someone with any familiarity with this project able to advise how you'd
handle that in docli?

~~~
granra
All the variables in in the `Commands` and `AllOtherCommands` are bools.

In Go you can do `a, b, c bool` and they'll all be of type bool.

~~~
pushpop
Yeah I got that. My point is that ‘workspace’ isn’t a Boolean flag in
terraform. It requires additional flags to function, eg

    
    
      terraform workspace new granra
    

‘workspace’ is effectively the CLI flags equivalent of a submenu.

~~~
granra
Oh I see. It looks like docli sets the flag as true if it was passed as a
parameter to the program.

So you do:

var terraform Terraform

args.Bind(&terraform)

if terraform.Workspace {

    
    
      // do workspace stuff
    

}

I think.

EDIT: I don't know how hackernews formatting works :/

~~~
pushpop
That seems really messy to be honest because you can’t then ensure flags are
nested correctly.

I guess for simple purposes this is fine though.

------
mongol
For my purpose, go-flags was a great fit.

[https://github.com/jessevdk/go-flags](https://github.com/jessevdk/go-flags)

------
henvic
cobra is working pretty well for my needs:
[https://asciinema.org/a/192043](https://asciinema.org/a/192043)

Nice to see a declarative approach, though. It certainly looks more natural.
I'm certainly going to give it a try.

------
jlesk
I really like the line art logo on the site, but it's 2.4 MB (avatar.png).

Might want to size it down and run it through TinyPNG. :)

~~~
celicoo
Oh, I didn't notice how big it is! I will fix that as soon as possible. Thanks
for the feedback.

------
bfrydl
It's a little strange that I had to open the tutorial to find out what
language this is for.

~~~
skocznymroczny
I was going to guess Rust, but turns out it's Go.

~~~
99052882514569
Wouldn't `gocli` be a better name then?

~~~
bitcoinofficial
Does having a programming language name in a program name make the program
better? I don't get it, sorry.

~~~
lucideer
It certainly makes it a lot easier to understand what it's for...

------
kvakvs
Please put the language it is intended for somewhere as close to the page top
as possible. The world isn't all Go.

