Follow

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 #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.

https://docs.raku.org/language/create-cli#index-entry-MAIN

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

@fribbledom

Doesn't Cobra (github.com/spf13/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.

@veer66

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

@manuelcaeiro

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.

@fribbledom
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.

@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
Mastodon

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!