Support formatting of CLI output

[rturner3]

It would be convenient to have more standardized and/or customizable formatting for the output of spire-server commands to simplify scripting. The primary use case I've identified so far is during development where you want to create N number of registrations for a local SPIRE Server + Agent, then after running some tests and tearing down the Agent, run a different script to delete all N registrations. This is not very easy to do today since the output of the commands is in a custom format, e.g. for spire-server entry show:

Entry ID      : aaaf0c2a-cf34-415b-99f7-f8071a2a0c69
SPIFFE ID     : spiffe://example.org/workload/1
Parent ID     : spiffe://example.org/host
TTL           : default
Selector      : unix:uid:foobar

Parsing the output of this command to scrape entry IDs to delete with spire-server entry delete is non-trivial, and requires using something like sed to apply a regex against the output.

It would be nice to have options for CLI commands' output formatting, such as printing as JSON or YAML. Another option could be to support usage of Go templates so that only user-specified fields are printed. This also gives the user the power to define the format of the output for their particular use case.

[mcpherrinm]

I'd suggest directly using the API, maybe with a python script, as a workaround to the CLI being unfriendly to automation.

Adding a -json flag seems reasonable to me though.

[rturner3]

I'd suggest directly using the API, maybe with a python script, as a workaround to the CLI being unfriendly to automation.

Adding a -json flag seems reasonable to me though.

Using the API directly would solve my particular use case, but it is also undesirable in terms of implementation complexity since it requires knowledge of how to use gRPC with SPIRE and some script environment bootstrapping to ensure the right packages are installed.

[evan2645]

a formatter flag that is applied uniformly across all CLI output sounds like a great addition. It also sounds like it could be a good deal of work - anyone looking to work on this issue should probably leave a comment here first so we can agree on direction.

A refactor of the SPIRE Server APIs is currently in flight, and new protos are being defined for common resources like registration entries and attested agents. I wonder if this work is best done while porting the CLI utilities to use the new APIs.

[ghost]

Hi, I'm interested in taking this up.

Is there already a path forward that you have in mind, or should I come back with a proposal?

[evan2645]

Hi @gabece thanks for pinging us here!

The new APIs are done, but as far as I know there's still quite a mess left behind in the CLI code. I still think this would be a great addition so long as we can apply it uniformly. I don't have any ideas on how to best move forward, perhaps @azdagron does ... but it would be great to hear what you're thinking too on how to best tackle it in a consistent way!

[azdagron]

Yes, I'd love to hear a proposal! I have my own ideas on how this can happen but I don't see anything but advantages to having more than one proposal.

[ghost]

Hi @azdagron, sorry for the late reply!

Here are my initial thoughts:

1. A -format flag will be used to determine which format should be used for the CLI output: for example, bin/spire-server entry show -format json
2. The implementation details can live in cmd/printer/<format>: for example, proto --> JSON will be in cmd/printer/protojson, while internal struct --> JSON can live in cmd/printer/json. The API contracts of protojson and json can look something like Print(m proto.Message) and Print(v interface{}), respectively.
3. The -format flag should only be added to CLI commands that return a list, such as agent list, entry show, etc. Since a message is returned when running some of these commands, the JSON structure can be something like:

{
  "msg": "Found 2955 entries",  // msg will be the key for the message of every CLI output
  "items": []                   // items will be the key for every different output item
}

I have a few questions:

1. Do we need to consider API structs that aren't proto messages?
2. Do you think we should apply this structured JSON feature to CLI commands that output only a single sentence, such as count, or some .pem data? I'm not familiar with common scripting patterns of folks who use this CLI.

I'm new to SPIRE, so I'm open to suggestions and even clear guidance if that's easier for you folks.

[evan2645]

hey @gabece thank you for your thoughts on this. We got a nudge from @kfox1111 so I went ahead and took a swing at implementing something similar to what you described in PR #2650 .. there are a couple divergences here or there, but would be great to get your thoughts if you have time

[ghost]

Hey @evan2645, thanks a lot for dong this! Feel free to ignore my questions on your PR if you're swamped; otherwise, it looks good to me 😃

[ryysud]

Hi @azdagron @evan2645, Is TODO in this issue to modify all commands of spire-server and spire-agent to use cliprinter package? Or only spire-server agent list and spire-server entry show commands?

[guilhermocc]

Hi, I'm interested in taking this issue for using the new cli printer for the rest of the commands, could it be assigned to me, please?