Fix up flag descriptions and organize into flagsets

[tstirrat15]

Problem Statement

The current set of flags shows up in a big blob. It'd be nice to both elaborate on some of the descriptions and organize them into flagsets that would make the --help output a bit better organized.

This is one of a set of improvements that we want to make to the SpiceDB CLI - others will be forthcoming.

Solution Brainstorm

No response

[tstirrat15]

Here's an example of desired output from Jimmy's spike on the thing:

$ ./spicedb memory serve-grpc --help
Serve the SpiceDB gRPC API services

Usage:
  spicedb memory serve-grpc [flags]

Examples:
  spicedb memory serve-grpc --grpc-preshared-key secretKeyHere
  spicedb memory serve-grpc --grpc-preshared-key secretKeyHere --grpc-tls-cert path/to/cert --grpc-tls-key path/to/key

gRPC Flags:
      --grpc-addr string             address to listen on (default ":50051")
      --grpc-enabled                 enable the gRPC server (default true)
      --grpc-preshared-key strings   preshared key(s) for authenticating requests
      --grpc-tls-cert string         local path to the TLS certificate
      --grpc-tls-key string          local path to the TLS key

API Flags:
      --api-preconditions-limit uint16       max preconditions allowed per write and delete request (default 1000)
      --api-quantization-interval duration   boundary interval with which to round the revision (default 5s)
      --api-quantization-staleness float     percentage of quantization interval where stale revisions can be preferred (default 0.1)
      --api-readonly                         prevent any data modifications
      --api-schema-prefix-required           require prefixes on all object definitions
      --api-stream-timeout duration          max duration between stream responses (default 30s)
      --api-updates-limit uint16             max updates allowed per write request (default 1000)

Dispatch Flags:
      --dispatch-depth-limit uint32   max dispatches per request (default 50)

Data Seeding Flags:
      --seed strings            local path to YAML-formatted schema and relationships file
      --seed-overwrite          overwrite any existing data with the seed data
      --seed-timeout duration   max duration writing seed data (default 10s)

Observability Flags:
      --metrics-addr string            address to listen on for serving Prometheus metrics (default ":9090")
      --metrics-enabled                enable the metrics server (default true)
      --metrics-tls-cert string        local path to the TLS certificate
      --metrics-tls-key string         local path to the TLS key
      --otel-endpoint string           OpenTelemetry collector endpoint - the endpoint can also be set by using enviroment variables
      --otel-insecure                  connect to the OpenTelemetry collector in plaintext
      --otel-provider string           OpenTelemetry provider for tracing ("none", "otlphttp", "otlpgrpc") (default "none")
      --otel-sample-ratio float        ratio of traces that are sampled (default 0.01)
      --otel-service-name string       service name for trace data (default "spicedb")
      --otel-trace-propagator string   OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c")
      --pprof-block-profile-rate int   sets the block profile sampling rate
      --pprof-mutex-profile-rate int   sets the mutex profile sampling rate

Miscellaneous Flags:
      --skip-release-check            if true, skips checking for new SpiceDB releases
      --termination-log-path string   define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default

Global Flags:
      --log-format string   format of logs ("auto", "console", "json") (default "auto")
      --log-level string    verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")

For this work, we're mostly focusing on description updates and the grouping; ignore the structure of the command at the top of the output.

[vroldanbet]

@tstirrat15 I believe this is done now?

[tstirrat15]

The first part of it is; the second part would be reorganizing the commands similarly to #2021, where the datastore flags end up filtered down to just those flags that are relevant for a particular datastore.

I'm happy to let that be a different issue, though.

[vroldanbet]

It seems to me that's out of scope (fix descriptions and organize into flagsets is really done) for this issue and I'd create a new one capturing that problem.

[tstirrat15]

Yeah, agreed.

[tstirrat15]

@vroldanbet captured in #2055