Our great sponsors
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
-
cli-guidelines
A guide to help you write better command-line programs, taking traditional UNIX principles and updating them for the modern day.
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
https://github.com/Textualize/trogon
> Ultimately we would like to formalize this schema and a protocol to extract or expose it from apps. This which would allow Trogon to build TUIs for any CLI app, regardless of how it was built. If you are familiar with Swagger, think Swagger for CLIs.
it's not complete, but I've been thinking about this problem for years and have been thinking about how to solve it.
I am working on it here: https://github.com/jdx/usage
It's mostly just a README right now, and I'm still iterating on it, talking to friends, but I think I'm getting close. My hope is within the next month or two I might have a usable alpha release of it.
If you have any thoughts on my desig lmk.
A few things that can help with memory:
- spaced repetition for stuff that you use sporadically. I use Anki, it's great. For how to use it, this article is great: https://borretti.me/article/effective-spaced-repetition. I've found a positive feedback loop where the more I know how to do things without looking anything up, the more I use the CLI, the easier I remember things, the more things I discover, etc. I read once that when learning a new language, you should aim for content where you know 80%/90% already. It seems to be true for learning the CLI, and especially for integrating that learning into my day to day job.
- sd (https://github.com/ianthehenry/sd) for lowering the cost of creating a "documented alias". Before that I made aliases with either alias, or bash functions, all starting with "," to quickly see all which are "mine" (I read that trick in an article that I can't find), now the more complex stuff is in sd with some documentation.
You probably already know, but just in case you don't, you might read about http://docopt.org/ It seems to me a lot of your usage ideas could be refinements of / tooling around docopt-style interfaces.
There is also generating the whole thing from a function signature (e.g. https://github.com/c-blake/cligen ) since then CLauthors need not learn a new spec language, but then CLauthors must add back in helpful usage metadata/semantics and still need to learn a library API (but I like how those two things can be "gradual"). It's a hard space in which to find perfection, but I wish you luck in your attempt!
Capturing these guidelines is one of the primary reasons that https://clig.dev/ exists.
Definitely not my idea, but is encouraged by built-in tools like python's argparse [0] or node's util.parseArgs [1] which definitely guide you toward's this "short"/"long" style.
[0]: https://docs.python.org/3/library/argparse.html
[1]: https://nodejs.org/api/util.html#utilparseargsconfig
Ive sort of managed to implement something to this effect in python, and from another comment made me consider yanking it out to its own library.
I made a process where args are now in a toml file, with some various data for different operations, like whether its available in the CLI or API library, its arg flags, help text required value type, etc. From that, i can generate argparse args, documentation, code for other things, etc. Right now im generating args, docs, and a js code block from the same structure.
Heres the toml file: https://gitlab.com/accidentallythecable-public/prover-suite/...
And some docs that were generated from that: https://gitlab.com/accidentallythecable-public/prover-suite/...
Maybe it will give you some ideas on yours
I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)
Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...
Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...
I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)
Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...
Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...
I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)
Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...
Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...
I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)
Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...
Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...