yaml usage

[jdx]

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:

name: mycli
version: 1.0.0

flags:
  "-u --user <user>":              # string flag
  "-v --verbose...":               # count flag (implicit from ...)
  "-q --quiet":                    # boolean flag
  "--color/--no-color":            # negatable boolean

commands:
  server:
    commands:
      start:
        flags:
          "-p --port [port:number=8080]":     # optional number with default
          "-h --host [host=localhost]":       # optional string with default
          "-d --daemon":                      # boolean

      config:
        commands:
          set:
            args:
              "<key:host|port|timeout>":        # enum choices
              "<value>":                        # required string
            flags:
              "--restart/--no-restart":         # negatable

          export:
            flags:
              "--format <fmt:json|yaml|toml=yaml>":  # enum with default
            args:
              "[output]":                       # optional output file

  deploy:
    args:
      "<environment:staging|production>":      # required enum
      "<files>...":                            # one or more files
    flags:
      "-t --tag <tag>...":                    # repeatable
      "--dry-run":                            # boolean

completions:
  environment:
    run: |
      echo 'staging
      production'

thoughts?

[jdx]

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

[jdx]

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'

[jdx]

I think I don't like this in part because it would make json schema not work correctly

[jdx]

related, I could build sdks for popular languages so people don't need to write parsers themselves

[booniepepper]

Do you mean Usage SDKs?

There are parsers available for a lot of languages, although just skimming through the projects, some are going to be too low-level for basic use. https://kdl.dev/#implementations

[booniepepper]

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

[nashjain]

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

[jdx]

It's not going to happen despite what I said here. The syntax is too ugly particularly with mise tasks.

[nashjain]

Would you be open to supporting both YAML and KDL, if someone build the YAML part?

[jdx]

No, that would double the complexity for anyone building an SDK