Replies: 5 comments 5 replies
-
|
the issue of putting a lot of logic into the this definition string is that it makes parsing this a lot harder which hurts usage's use-case of being a "standard" for CLIs. I think I'm ok with that generally since I think something users like that looks good and works well for authors of specs will be something people would eventually get used to for parsers. It's also so easy to write parsers with AI tools nowadays |
Beta Was this translation helpful? Give feedback.
-
|
getting a little crazy with tags: name: mycli
version: 1.0.0
# Top-level flags and commands together
!flag "-v --verbose...": { help: "Enable verbose output", global: true }
!flag "-q --quiet": { help: "Suppress output", global: true }
!cmd server: { help: "Manage the server" }
!cmd start: { help: "Start the server" }
!flag "-p --port [port:number=8080]": { help: "Port to listen on" }
!flag "-h --host [host=localhost]": { help: "Host to bind to" }
!flag "-d --daemon": { help: "Run in background" }
!cmd stop: { help: "Stop the server" }
!flag "-f --force": { help: "Force stop" }
!cmd config: { help: "Manage server configuration" }
!cmd set: { help: "Set a server config value" }
!arg key: { help: "Configuration key" }
!arg value: { help: "Configuration value" }
!flag "--restart": { help: "Restart server after change" }
!cmd get: { help: "Get a server config value" }
!arg key: { help: "Configuration key" }
!flag "--json": { help: "Output as JSON" }
!cmd list: { help: "List all server config values" }
!flag "--filter <pattern>": { help: "Filter by pattern" }
!cmd config: { help: "Manage global configuration" }
!cmd set: { help: "Set a config value" }
!arg key: { help: "Configuration key" }
!arg value: { help: "Configuration value" }
!cmd get: { help: "Get a config value" }
!arg key: { help: "Configuration key" }
!complete key:
run: |
echo 'host
port
debug' |
Beta Was this translation helpful? Give feedback.
-
|
related, I could build sdks for popular languages so people don't need to write parsers themselves |
Beta Was this translation helpful? Give feedback.
-
|
My initial reaction is that I just really wish kdl would take off. It nests well like yaml with less ambiguity around how strings will be handled |
Beta Was this translation helpful? Give feedback.
-
|
@jdx since you define Usage as an OpenAPI-like specification for CLIs, I would expect YAML support. Many people are familiar with YAML and the tooling ecosystem is solid. So my vote would be to add support for YAML (back that with a jsonSchema for the usage yaml spec.) |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
kdl was a fun experiment, but I think ultimately I want to go with something more standard in the industry. One thing I'm conscious of is that I want concise configs which, while they make parsing harder, make authoring and more importantly reading usage specs a lot better. A lot of what I'm referring to here is how you can do
flag "-u --user <user>"which defines several properties about a flag (what its short char is, what its long flag is, what its name is, that it accepts a required arg, and that arg's name). Granted most of those are just "user" but still, this makes it easy and obvious to modify any one of those things without knowing much.A lot of this inspiration comes from docopt. I think usage does a pretty good job at taking the things docopt did right but by not having everything defined as help it makes it easier to see the structure of an entire CLI.
Anyhow, I'm thinking about a v3 of usage which would default to using yaml—it's clearly better than json/toml for CLI definitions. (kdl would still be backwards-compatible) I'm thinking about what else could be embedded in that string to keep the conciseness we have with kdl. I went a bit crazy and came up with some ideas:
thoughts?
Beta Was this translation helpful? Give feedback.
All reactions