Skip to content

Latest commit

 

History

History
99 lines (73 loc) · 3.78 KB

output.md

File metadata and controls

99 lines (73 loc) · 3.78 KB

Output Formats

--output / -o is a global flag. It takes one of four values:

Value Shape
json One JSON envelope carrying version and kind (default)
jsonl JSON Lines: one object per line
csv CSV with a header row
table Human-readable text — a summary line, an ASCII tree, or a diagram, depending on the command

Anything else is rejected before the command runs:

$ rootline query docs/ -o sdlkfj
Error: unknown output format "sdlkfj" (use json, jsonl, csv or table)

The check is case-sensitive and rejects the empty string. -o JSON is an error, not a synonym for -o json.

Not every command supports all four

jsonl and csv are row formats. They need a flat, column-shaped result, which only query --select produces. Every other command emits a nested envelope with no defensible flattening, so it declares json and table only, and an unsupported combination is rejected rather than quietly downgraded:

$ rootline stats docs/ -o csv
Error: rootline stats does not support output format "csv" (use json or table)
Command Supported
query json, table; jsonl and csv require --select
analyze, describe, explain, fix, graph, migrate, repair, schema propose, schema apply, stats, tree, validate json, table
completion, hooks, init, new, set none — these emit human text or write files and never consult --output

The matrix is declared in one table (cmd/rootline/output.go) and a test walks the whole command tree asserting every command has an entry, so a new command cannot ship without deciding what it supports.

query --count supports only json and table, and cannot be combined with --select. These conditional format checks run before schema discovery or scanning:

$ rootline query docs/ --count -o csv
Error: --count does not support output format "csv" (use json or table)

What table means per command

table is "the human-readable rendering", which is not the same rendering everywhere:

  • stats — a summary line
  • tree — the ASCII tree
  • graph — the diagram selected by --format dot|mermaid
  • query, validate, describe, explain — a text table or report

query --count -o table renders a single Count column and one decimal row, instead of the JSON rootline/count envelope returned by -o json:

$ rootline query docs/ --count -o table
Count
-
12

tree and graph previously produced their diagram for any value that was not json, so -o jsonl returned box-drawing characters or Graphviz DOT at exit 0. The diagram is now bound to -o table and to nothing else.

--field

--field extracts a dot-path from the JSON envelope, so it applies to -o json only. Combining it with any other format — or with a command that emits no envelope — is an error, not a silent no-op:

$ rootline stats docs/ -o table --field kind
Error: --field requires --output json: extraction reads the JSON envelope, and "table" has none

The flag is repeatable, as its help has always claimed. One path emits the bare value; several emit a JSON array in flag order. Full syntax in Describe.

graph --check

--check is a text-plus-exit-code validator; it emits no envelope. Passing --output explicitly alongside it is an error rather than a silent no-op:

$ rootline graph docs/ --check -o json
Error: --check does not support --output: it emits a text report and an exit code; drop
--output, or drop --check to get the rootline/graph envelope, which carries the same
cycles and broken_links

The default -o json is not an explicit request, so rootline graph docs/ --check keeps working unchanged.