Add human-readable output format

[n8agrin]

Summary

Adds a human-readable output format alongside JSON, modeled after gh CLI. Lists become stylized lipgloss tables; single resources become key: value blocks; mixed objects (e.g. AI search → answer + sources) render each section under its own heading. A spinner runs on stderr for long requests. JSON mode stays the default when piped so omni … | jq … pipelines keep working.

Highlights

• Three-level precedence for format selection: -o/--format flag > OMNI_OUTPUT_FORMAT env > defaultOutputFormat in config.json > auto (human on TTY, JSON when piped).
• Lipgloss-rendered tables with box-drawing borders, bold headers, dimmed UUID columns, gray timestamps. Color auto-disables when piped.
• Humanized labels: modelKind → Model Kind, MODEL_KIND → Model Kind, created_at → Created At. No more SHOUTING headers.
• Shape heuristics for the non-uniform Omni response shapes: {records, pageInfo} lists, resource-named arrays ({connections: […]}), success envelopes ({success, message, <resource>}), bare arrays, single resources, and mixed scalar+array.
• Null scalars are hidden in human mode so "error": null doesn't render as a scary Error: - line.
• Rotating spinner on stderr while the HTTP request is in flight — cycles through 15 playful BI-flavored phrases every 3 seconds ("consulting the warehouse…", "aligning facts and dimensions…", "squinting at the query plan…", …). Only shown when stderr is a TTY and format is human; piped/scripted invocations stay quiet.
• omni config set-format <json|human|auto> subcommand to persist a preference.

Example output

./bin/omni models list --modelkind SHARED:

┌──────────────────────────────────────┬────────────────────────────┬────────────┬────────────┐
│ Id                                   │ Name                       │ Model Kind │ Created At │
├──────────────────────────────────────┼────────────────────────────┼────────────┼────────────┤
│ ef0ba8e6-7bbc-4f3f-9097-7d10a764c60f │ GSBQ                       │ SHARED     │ 3h ago     │
│ 7ea1fa6d-932f-4d03-aeac-9084a516aad4 │ eCommerce New              │ SHARED     │ 3y ago     │
│ 0c056618-c536-438d-ba04-821cf5f37ad6 │ BigQuery Demo              │ SHARED     │ 3y ago     │
└──────────────────────────────────────┴────────────────────────────┴────────────┴────────────┘

./bin/omni ai search-omni-docs "how to add a format to field?" — mixed scalar+array shape renders the answer body (including nested markdown code fences) and the sources table side by side. The outer fence below is four backticks so the inner yaml block stays intact:

Answer
  To add a format to a field in Omni, use the `format` parameter on a dimension or measure.

  ## Basic syntax:

  ```yaml
  field_name:
    format: <format_string>
  ```

  See [Formatting values](/modeling/models/format-values) for the complete reference.

Sources
┌─────────────────────────────────────────────┬────────────────────────────────────────────────────────────┐
│ Title                                       │ Url                                                        │
├─────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ Modeling - Dimensions - Parameters - Format │ https://docs.omni.co/modeling/dimensions/parameters/format │
│ Modeling - Models - Format Values           │ https://docs.omni.co/modeling/models/format-values         │
└─────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘

Commits

1. Add output format resolver with flag/env/config precedence
2. Add human-readable output formatter
3. Wire --format flag and omni config set-format subcommand
4. Humanize table headers and key labels
5. Render tables with lipgloss
6. Hide null scalar fields in human mode
7. Show a spinner while the API request is in flight
8. Rotate spinner phrases while waiting on the API
9. Swap spinner phrases that hinted at mutation

Test plan

• make test — resolver precedence, humanizeKey, shape heuristics (records list, resource-named list, bare array, single resource, success envelope, empty body, non-JSON passthrough, mixed scalar+array, null-skip regression)
• make build
• ./bin/omni models list --format human renders a bordered table; | cat drops ANSI (termenv auto-downgrade)
• ./bin/omni ai search-omni-docs "…" renders Answer block + Sources table
• ./bin/omni ai generate-query <id> "…" hides null Error, shows the Result table
• OMNI_OUTPUT_FORMAT=human ./bin/omni models list | cat forces human
• ./bin/omni config set-format human persists the preference to config.json
• Spinner only appears when stderr is a TTY and format is human (verified via 2>/dev/null and --format json)

🤖 Generated with Claude Code

[n8agrin]

@claude review this

[n8agrin]

sets the format default

[n8agrin]

This might be brittle. Something to watch out for.

[n8agrin]

@cmruderman this one is interesting:

Shape heuristics for the non-uniform Omni response shapes: {records, pageInfo} lists, resource-named arrays ({connections: […]}), success envelopes ({success, message, }), bare arrays, single resources, and mixed scalar+array.

I've gotten a request to generally abstract all the api responses behind a uniform data structure / format. We can talk about it in the next couple of weeks. Not sure it needs to be at the API layer, but I was surprised that OpenAPI didn't require one.