There should be a swagger-like standard for command-line tools... 🤔

What do I mean by that?

Wouldn't it be great if tools provided an interface to an automated documentation of their own command-line parameters and flags?

This could be used to provide interactive help while typing on the prompt, as well as accurate auto-completion in your shell.

@fribbledom maybe we could hook this into man pages.... and autocomplete that checked man would rock.


I'd almost look at it the other way round:

Let the man pages be generated from the self-documenting feature of the tools! 👌

@fribbledom If it gets me man pages again for this infuriating slew of new commands, I'll take it!

@fribbledom The first time I really learned Linux, was by having discovered the xman command .. and reading the /entire set/ of man pages on the system, encyclopedia style, front to back, while trying out everything I could. I have no idea how I would do something like that on a modern system.

@tomasino @feonixrift @fribbledom It does, and it works well for simple tools.

The problem is that only options are really specified similarly enough that it's parsable. Subcommands and other kinds of arguments are specified differently in each.

E.g. the kinds of files or commits a `git` subcommand takes just aren't automatically translatable from the man page.

Also the option descriptions are often too verbose to show in completions.

@feonixrift @fribbledom I'm imagining this hypothetical parser being directed to the old man pages for sudo that used to include a crash course in BNF grammars for no good raisin, and crashing from angst

@cathal @fribbledom I'm borrowing the phrase 'for no good raisin' forever.

@feonixrift @fribbledom Oo and I just imagined trying autocomplete on `shred` and getting instructed to just incinerate the drive, as the man pages used to before someone sensible spoiled all the fun

@fribbledom #Raku provides this to any command line utility, by automatically generating usage/help text for parameters for the MAIN sub. If you add type constraints to these parameters, the usage text will include this. If you add comments, the usage text will include this too. Same goes for default values.

@inexcode @fribbledom That's hand-rolled. See /usr/share/zsh/functions/Completion/Unix/_man.

@fribbledom Many libraries for cli tools now provide autogenerated --help and even autogenerated bash completion scripts!


Doesn't Cobra ( check all of these boxes? :blobthinkingeyes:
Auto-generated help as well as BASH and ZSH completion works like a charm

@fribbledom AutoCAD, for all its many faults, is a bit of a model here in that you can move back and forwards between menu selections, dialog boxes and mouse actions to and from writing a command in a box at the bottom.

As you do the mouse actions it shows you the equivalent command in the command box.

As you type a command it prompts you to fill in the appropriate data, e.g., a point on the screen which you can click on or type the coordinates.

Would be great to have a shell like this.

@fribbledom fish sort of does this already. It has a built in completion format and comes stock with a load of completion information for things like core utilities and very common programs. There are also several packages that provide fish completions for other specific programs, or you can write your own too.

They're great because not only do they provide completion, but they also attach a brief description of each option, so with a keybind (double Tab iirc) it'll show you the docs for each option.


That's a common way to retrieve the flags, yeah. It's neither self-documenting nor accessible through an API though.


I think you misunderstand what I want.

I want apps to be able to return a JSON (or XML or TOML or whatever) definition of their own command-line syntax, so other things (like your shell's auto-completion feature, for example) can process that information to provide a better user experience.

@fribbledom So, I did. I was probably thinking about apps when I read tools. Thank you for calling my attention.

Python's ability to let an IDE do just that is one of the main reasons I don't want to use anything else these days.

@fribbledom this would be amazing, let's start a task force and get it done

@robjloranger @fribbledom yeah, seriously. If anyone wants to put together a project for this, I'm in!

@gudenau @fribbledom I expect fish lets you define external meta-data for commands (similar to the autocomplete files for bash, zsh, etc). But the point here is to have a standardized way for a command to emit its own metadata.
This way, autocomplete and documentation could work out of the box on any shell that supports the standard, no external definition necessary.

@gudenau @fribbledom Possibly. If fish defines a broadly-usable metadata format you might be able to use it as-is. In that case, existing command metadata could also be leveraged in broader contexts.

@0x0x @fribbledom It's got an implementation already so adding an API to that wold be somewhat easy. Assuming the code isn't a huge mess.

@fribbledom It would be nice if the command args would appear as a fly-out menu to the terminal you were in. Yes, I can tab between terminals where one is the man page and all, but its small things that improve the user experience, I find.

@itsfarseen @Tusky

I'm not sure I understand this question correctly. What do you want to do in @Tusky?

@fribbledom @Tusky oops.. I was replying to your other post.. how did it appear here 😅

Sign in to participate in the conversation

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!