Output Modes

Output Modes

Every command can render in three formats. All three are pure projections of the same typed result — they can never silently diverge.

Mode	Flag	Audience
Text	(default)	Humans. Color only on a TTY.
JSON	--json	Machines. Versioned contract + error envelope.
LLM	--llm	Context windows. Markdown with ranges + "why".

Text (default)

Human-readable, color on a TTY:

$ columbus search "parse config"
1. parseConfig  [function]  (score 0.74, exact name match)
   src/config.ts:4
   function parseConfig(env: Record<string, string>): Config {

JSON (--json)

A stable, versioned contract for tools and agents:

$ columbus search "parse config" --json
{"command":"search","query":"parse config","kind":"all","total":7,
 "ok":true,"schema_version":1,"hits":[ … ]}

Every payload carries command, ok, and schema_version; errors use a canonical envelope. See JSON Contract & Errors.

LLM (--llm)

Markdown shaped for a model's context window — ranked results, exact ranges, a short "why" per hit, and fenced snippets:

$ columbus search "parse config" --llm
# Search: parse config

7 result(s).

## parseConfig (function)

- location: `src/config.ts:4-6`
- signature: `function parseConfig(env: Record<string, string>): Config {`
- score: 0.74 (exact name match); risk: low

​```
export function parseConfig(env: Record<string, string>): Config {
  return { port: Number(env.PORT ?? 8080), host: env.HOST ?? "localhost" };
}
​```

Streams

Results go to stdout; diagnostics and errors go to stderr — so you can pipe --json cleanly. Color/format obey the rules in Color & Environment.

Related

JSON Contract & Errors · Exit Codes · Color & Environment