Add --format (plain | json) argument to display any output as formatted JSON or plain text (default)

[cardoso]

From clig.dev:

Display output as formatted JSON if --json is passed. JSON allows for more structure than plain text, so it makes it much easier to output and handle complex data structures. jq is a common tool for working with JSON on the command-line, and there is now a whole ecosystem of tools that output and manipulate JSON.

It is also widely used on the web, so by using JSON as the input and output of programs, you can pipe directly to and from web services using curl.

My use-case for this would be a web-based dashboard that can perform some operations like build, up, and deploy. Ideally the spin command itself and any subcommands would obey this flag.

This could also help with adding features to the vscode extension like https://github.com/fermyon/spin-vscode/issues/1 and https://github.com/fermyon/spin-vscode/issues/2 for instance while avoiding duplication of logic there.

[itowlson]

We've got a --format json flag on spin templates list, and whatever we choose for other commands should be consistent. That said, it's hidden in the UI as it was done for programmatic use, primarily VS Code, and nothing uses it yet so we can change the name for sure. I would prefer a --format or --output-format or something like that to a plain --json, though, so that we can extend it to --formal xml (the revival starts here) or whatever in future.

A couple of specific comments:

• build may be a tricky one, because it basically just passes on stdout from the invoked command(s), which would not be JSON. We'd need to consider how this would work.
• up produces output but then keeps running: the output stream doesn't end when the app is ready. So a consumer would need to know when the "ready" JSON had completed. Additionally, with up --follow (which may become the default in future), the output include streaming raw stdout from the Wasm components.

To be clear, I'm definitely in favour of designing things with an eye on programmatic consumption, and JSON is the way to do that - I'm just flagging some considerations that have slowed us down on implementing it more widely.

[cardoso]

@itowlson that makes sense. I think the commands where the implementation needs more thought could be left out until there's a good enough use case to justify the effort. The majority are fairly simple.

I'd definitely give it some thought if I'm implementing this and likely write a separate issue. Build and up could just give a status, or they could give line-separated updates in json format, etc. But I'd leave it out until there's a use case to validate the approach.

[itowlson]

Also requested as part of #2555

[me-diru]

I will take a stab at this one :D

[lann]

It looks like spin templates list --format json already works, though it is hidden from --help for ~unknown~ reasons known only to @itowlson.

I don't think we want to add --format to all spin commands, so if there are additional features needed here we should probably figure out scope before starting.

[itowlson]

I think the reason was I didn't want to clutter the UI for something that was intended solely for programmatic use. That was probably a bad call (who am I kidding, it was clearly a bad call).

Agree that step 1 is to write a list of which commands and outputs should be JSONable. @me-diru are you comfortable taking a stab at this, or would you prefer to have that provided as an input to your work?

[me-diru]

This could be a good excuse to explore all commands and see which outputs are JSONable. I will start with that. Thanks!

[me-diru]

These are the potential commands/subcommands where the JSON output can be useful for others. The ? are the ones I am not sure about.

• spin build?
• spin cloud apps list
• spin cloud apps info
• spin cloud key-value list
• spin cloud logs?
• spin cloud sqlite list
• spin cloud variables list
• spin help?
• spin plugins search?
• spin plugins list
• spin templates list
• spin templates upgrade?
• spin cloud-gpu init

Note: I have excluded interactive output or one-line output indicating a task is done from the list. Please let me know if I am going in the right direction. They seem to be in align with suggestion given in #2555 parsable JSON outputs

[lann]

I think the only thing from this list explicitly called out in #2555 (that isn't already secretly implemented) would be spin plugins list. For the rest I would probably wait until we see an actual need.