Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(cli): let a caller ask for the answer without the scaffolding (#703)
Ian Hockb307558d2372
diff --git a/ix-cli/src/cli/__tests__/quiet-and-fields.test.ts b/ix-cli/src/cli/__tests__/quiet-and-fields.test.tsnew file mode 100644index 00000000..250e6898--- /dev/null+++ b/ix-cli/src/cli/__tests__/quiet-and-fields.test.ts@@ -0,0 +1,134 @@+// Copyright 2026 Ix Infrastructure Inc.++import { Command } from "commander";+import { afterEach, describe, expect, it, vi } from "vitest";++import { renderEdgeResultsLlm, renderNodesLlm, sliceEdgeResults } from "../format.js";+import { renderSearchLlm } from "../commands/search.js";+import { renderInventoryLlm } from "../commands/inventory.js";+import { renderNote, renderSection, renderWarning } from "../ui.js";+import { parseFields, projectRow, setOutputShape } from "../output-shape.js";+import { registerOssCommands } from "../register/oss.js";++afterEach(() => setOutputShape({}));++function captured(fn: () => void): string[] {+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});+ try {+ fn();+ return spy.mock.calls.map((c) => String(c[0]));+ } finally {+ spy.mockRestore();+ }+}++const node = { id: "abcdef1234567890", kind: "function", name: "relativePath" };++describe("--fields", () => {+ it("parses a list, and nothing from nothing", () => {+ expect(parseFields("name,path,lines")).toEqual(["name", "path", "lines"]);+ expect(parseFields(" name , path ")).toEqual(["name", "path"]);+ expect(parseFields("")).toBeUndefined();+ expect(parseFields(undefined)).toBeUndefined();+ });++ it("keeps the caller's order, not the renderer's", () => {+ // `--fields path,name` is a request for a column layout; answering it in+ // the renderer's order ignores half of what was asked.+ setOutputShape({ fields: "path,name" });+ expect(projectRow([["name", "a"], ["kind", "function"], ["path", "src/a.ts"]]))+ .toEqual([["path", "src/a.ts"], ["name", "a"]]);+ });++ it("drops a name no row carries rather than inventing it", () => {+ setOutputShape({ fields: "name,lines" });+ expect(projectRow([["name", "a"], ["kind", "function"]])).toEqual([["name", "a"]]);+ });++ it("shapes search rows", () => {+ setOutputShape({ fields: "name,path" });+ const lines = renderSearchLlm(+ [{ name: "relativePath", kind: "function", id: "abcdef1234567890", path: "src/format.ts", score: 0.83 }],+ 1, [],+ );+ expect(lines[1]).toBe("node name=relativePath path=src/format.ts");+ });++ it("shapes edge rows and node rows", () => {+ setOutputShape({ fields: "name" });+ expect(renderNodesLlm([node])).toEqual(["node name=relativePath"]);+ const refs = renderEdgeResultsLlm(+ // #688 made this take a Slice rather than a bare array.+ sliceEdgeResults([{ id: "abcdef1234567890", name: "handleLogin", kind: "method", provenance: { source_uri: "src/a.ts" } }], 10),+ "callers", "verify", "graph",+ );+ expect(refs[1]).toBe("ref name=handleLogin");+ });++ it("shapes inventory rows", () => {+ setOutputShape({ fields: "path" });+ const lines = renderInventoryLlm("class", null, [+ { name: "Foo", kind: "class", provenance: { source_uri: "src/a.ts" } },+ ]);+ expect(lines[1]).toBe("file path=src/a.ts");+ });++ it("never touches the header, which is the answer's own bookkeeping", () => {+ // A projection that removed `total=` would make a partial list look+ // complete — the exact failure the truncation work exists to stop.+ setOutputShape({ fields: "name" });+ expect(renderSearchLlm([], 12, [])[0]).toBe("search count=0 candidates=12");+ });+});++describe("--quiet", () => {+ it("drops section titles and notes", () => {+ setOutputShape({ quiet: true });+ expect(captured(() => { renderSection("Evidence"); renderNote("run ix map"); })).toEqual([]);+ });++ it("keeps a warning, which is not decoration", () => {+ // A caller asking for less output is not asking to be told less about+ // something being wrong with the answer.+ setOutputShape({ quiet: true });+ expect(captured(() => renderWarning("source has changed"))).toHaveLength(1);+ });++ it("drops advisory diagnostics from a record stream", () => {+ setOutputShape({ quiet: true });+ const lines = renderSearchLlm([], 0, [{ code: "unfiltered_search", message: "broad" }]);+ expect(lines).toEqual(["search count=0 candidates=0"]);+ });++ it("keeps them when it was not asked to", () => {+ const lines = renderSearchLlm([], 0, [{ code: "unfiltered_search", message: "broad" }]);+ expect(lines).toHaveLength(2);+ });+});++describe("the flags themselves", () => {+ it("are on every command that renders an answer", () => {+ const program = new Command();+ program.name("ix");+ registerOssCommands(program);++ const pending = [...program.commands];+ const missing: string[] = [];+ while (pending.length > 0) {+ const command = pending.shift()!;+ pending.push(...command.commands);+ if (!command.options.some((o) => o.long === "--format")) continue;+ const has = (long: string) => command.options.some((o) => o.long === long);+ if (!has("--quiet") || !has("--fields")) missing.push(command.name());+ }+ expect(missing).toEqual([]);+ });++ it("are not on a command with no answer to shape", () => {+ const program = new Command();+ program.name("ix");+ registerOssCommands(program);+ const upgrade = program.commands.find((c) => c.name() === "upgrade")!;+ expect(upgrade.options.some((o) => o.long === "--quiet")).toBe(false);+ });+});diff --git a/ix-cli/src/cli/commands/inventory.ts b/ix-cli/src/cli/commands/inventory.tsindex 4a3d34c2..b74a7278 100644--- a/ix-cli/src/cli/commands/inventory.ts+++ b/ix-cli/src/cli/commands/inventory.ts@@ -8,6 +8,7 @@ import { resolveWorkspaceId } from "../bootstrap.js";import { resolveReadSystemId } from "../resolve.js";import { relativePath, printJson } from "../format.js";import { llmLine } from "../llm.js";+import { projectRow } from "../output-shape.js";import { normalizePathSeparators } from "../path-match.js";/**@@ -52,10 +53,10 @@ export function renderInventoryLlm(]));}for (const [path, names] of byFile) {- lines.push(llmLine("file", [["path", path], ["items", names.join(",")]]));+ lines.push(llmLine("file", projectRow([["path", path], ["items", names.join(",")]])));}for (const u of ungrouped) {- lines.push(llmLine("item", [["name", u.name], ["kind", u.kind]]));+ lines.push(llmLine("item", projectRow([["name", u.name], ["kind", u.kind]])));}return lines;}diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.tsindex 9a2dca0e..67241692 100644--- a/ix-cli/src/cli/commands/search.ts+++ b/ix-cli/src/cli/commands/search.ts@@ -10,6 +10,7 @@ import { scoreCandidate, resolveReadSystemId } from "../resolve.js";import { applyRoleFilter, roleHint } from "../role-filter.js";import { stderr } from "../stderr.js";import { llmLine, llmShortId } from "../llm.js";+import { isQuiet, projectRow } from "../output-shape.js";import { normalizePathSeparators } from "../path-match.js";/** Render `ix search` as llm records: a header line then one `node` row per hit (rank = order). */@@ -19,12 +20,16 @@ export function renderSearchLlm(): string[] {const lines = [llmLine("search", [["count", results.length], ["candidates", totalCandidates]])];for (const r of results) {- lines.push(llmLine("node", [+ lines.push(llmLine("node", projectRow([["name", r.name], ["kind", r.kind], ["id", llmShortId(r.id)],["path", r.path], ["score", r.score],- ]));+ ])));+ }+ // Advice, not findings: `--quiet` drops it. An error still reaches the+ // caller through the error path, which this is not.+ if (!isQuiet()) {+ for (const d of diagnostics) lines.push(llmLine("diagnostic", [["code", d.code], ["message", d.message]]));}- for (const d of diagnostics) lines.push(llmLine("diagnostic", [["code", d.code], ["message", d.message]]));return lines;}diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.tsindex 129df6fb..f09c98d7 100644--- a/ix-cli/src/cli/format.ts+++ b/ix-cli/src/cli/format.ts@@ -2,6 +2,7 @@import chalk from "chalk";import { llmLine, llmShortId } from "./llm.js";+import { projectRow } from "./output-shape.js";export type ResultSource = "graph" | "text" | "graph+text" | "heuristic";@@ -281,13 +282,13 @@ export function formatContext(result: any, format: string): void {export function renderNodesLlm(nodes: any[]): string[] {return nodes.map((n) => {const loc = rowLocation(n);- return llmLine("node", [+ return llmLine("node", projectRow([["kind", n.kind],["id", llmShortId(n.id)],["name", n.name || n.attrs?.name || n.attrs?.title || "(unnamed)"],["path", loc.path],["lines", lineSpan(loc)],- ]);+ ]));});}@@ -680,11 +681,11 @@ export function renderEdgeResultsLlm(}for (const ref of refs) {lines.push(ref.resolved- ? llmLine("ref", [+ ? llmLine("ref", projectRow([["name", ref.name], ["kind", ref.kind], ["id", llmShortId(ref.id)],["path", ref.path], ["lines", lineSpan(ref)],- ])- : llmLine("ref", [["kind", ref.kind], ["id", llmShortId(ref.id)], ["resolved", false]]));+ ]))+ : llmLine("ref", projectRow([["kind", ref.kind], ["id", llmShortId(ref.id)], ["resolved", false]])));}return lines;}diff --git a/ix-cli/src/cli/output-shape.ts b/ix-cli/src/cli/output-shape.tsnew file mode 100644index 00000000..d0699a14--- /dev/null+++ b/ix-cli/src/cli/output-shape.ts@@ -0,0 +1,76 @@+// Copyright 2026 Ix Infrastructure Inc.++import type { LlmFields, LlmValue } from "./llm.js";++/**+ * `--quiet` and `--fields`: what the caller wants off the answer.+ *+ * Both are properties of a run rather than of a payload, so the renderers read+ * them from here instead of every signature growing two parameters it only+ * forwards. Recorded once by the root `preAction` hook, the same way `--pretty`+ * is.+ */+let quiet = false;+let fields: string[] | undefined;++export function setOutputShape(shape: { quiet?: boolean; fields?: string }): void {+ quiet = shape.quiet === true;+ fields = parseFields(shape.fields);+}++/**+ * True when the caller asked for the answer without the scaffolding.+ *+ * "Scaffolding" is a narrow word here: section titles, `Resolved:` headers and+ * advisory hints. It is NOT the truncation records or the error records — a+ * caller asking for less output is not asking to be misled about what was cut,+ * and `--quiet` that hid `shown=50 total=212` would undo the one thing those+ * records exist for.+ */+export function isQuiet(): boolean {+ return quiet;+}++/** The fields the caller asked for, or undefined for all of them. */+export function requestedFields(): string[] | undefined {+ return fields;+}++/** `name,path,lines` -> `["name", "path", "lines"]`, or undefined. */+export function parseFields(raw: string | undefined): string[] | undefined {+ if (!raw) return undefined;+ const names = raw.split(",").map((f) => f.trim()).filter((f) => f !== "");+ return names.length > 0 ? names : undefined;+}++/**+ * Keep only the requested fields of one row, in the order the caller named+ * them.+ *+ * The caller's order, not the renderer's: `--fields path,name` is a request for+ * a column layout, and answering it in the renderer's order silently ignores+ * half of what was asked. A name that no row carries is dropped rather than+ * emitted empty — `llmField` already omits an absent value, so inventing a+ * `lines=` for a file would be the one shape this cannot produce honestly.+ *+ * Applies to rows, never to a header: `shown=`, `total=` and `truncated=` are+ * the answer's own bookkeeping, and a projection that removed them would make+ * a partial list look complete.+ */+export function projectRow(pairs: Array<[string, LlmValue]>): Array<[string, LlmValue]> {+ const wanted = fields;+ if (!wanted) return pairs;+ const byKey = new Map(pairs);+ const out: Array<[string, LlmValue]> = [];+ for (const key of wanted) {+ if (byKey.has(key)) out.push([key, byKey.get(key) as LlmValue]);+ }+ return out;+}++/** The same, for a renderer that builds its fields as an object. */+export function projectFields(fieldsIn: LlmFields): LlmFields {+ return Array.isArray(fieldsIn)+ ? projectRow(fieldsIn)+ : projectRow(Object.entries(fieldsIn));+}diff --git a/ix-cli/src/cli/register/oss.ts b/ix-cli/src/cli/register/oss.tsindex aad29156..4eb27eee 100644--- a/ix-cli/src/cli/register/oss.ts+++ b/ix-cli/src/cli/register/oss.ts@@ -41,6 +41,7 @@ import { registerMcpCommand } from "../commands/mcp.js";import { registerContextCommand } from "../commands/context.js";import { validateCliOptions } from "../options.js";import { setPrettyJson } from "../format.js";+import { setOutputShape } from "../output-shape.js";import {BUILT_IN_DEFAULT_FORMAT,DEFAULT_FORMAT_CHOICES,@@ -114,12 +115,14 @@ function configureOssOptions(root: Command): void {const visit = (command: Command): void => {ossCommands.add(command);const commandChoices = OPTION_CHOICES[command.name()] ?? {};+ let rendersRows = false;let rendersJson = false;for (const option of command.options) {const choices = commandChoices[option.attributeName()]?? (option.long === "--format" ? [...DEFAULT_FORMAT_CHOICES] : undefined);if (choices) option.choices(choices);applyDefaultFormat(command, option, choices, defaultFormat);+ if (option.long === "--format") rendersRows = true;if (option.long === "--format" && (choices ?? []).includes("json")) rendersJson = true;}// Declared here rather than 32 times by hand, and only where it means@@ -127,6 +130,17 @@ function configureOssOptions(root: Command): void {if (rendersJson && !command.options.some((option) => option.long === "--pretty")) {command.option("--pretty", "Indent JSON output (the default only when stdout is a terminal)");}+ // Declared here rather than on 33 commands by hand, and only where there+ // is an answer to shape. A command with no `--format` prints a status+ // line or nothing.+ if (rendersRows) {+ if (!command.options.some((option) => option.long === "--quiet")) {+ command.option("--quiet", "Drop headers, section titles and advisory hints");+ }+ if (!command.options.some((option) => option.long === "--fields")) {+ command.option("--fields <list>", "Keep only these fields on each row, in this order (e.g. name,path,lines)");+ }+ }for (const child of command.commands) visit(child);};visit(root);@@ -206,10 +220,12 @@ export function registerOssCommands(program: Command): void {configureOssOptions(program);program.hook("preAction", (_thisCommand, actionCommand) => {- // Before anything prints. `--pretty` is a property of the run, not of a- // payload, so the renderers read it from one place instead of threading a- // flag through every signature that ends in a `console.log`.- setPrettyJson(actionCommand.opts().pretty === true);+ // Before anything prints. All three are properties of the run, not of a+ // payload, so the renderers read them from one place rather than every+ // signature growing parameters it only forwards.+ const opts = actionCommand.opts();+ setPrettyJson(opts.pretty === true);+ setOutputShape({ quiet: opts.quiet === true, fields: typeof opts.fields === "string" ? opts.fields : undefined });// OSS commands only. The rules below read an option's *shape* -- `<n>`// means a non-negative integer, `--min-confidence` means 0..1 -- which isdiff --git a/ix-cli/src/cli/resolve.ts b/ix-cli/src/cli/resolve.tsindex b84277a0..434c097d 100644--- a/ix-cli/src/cli/resolve.ts+++ b/ix-cli/src/cli/resolve.ts@@ -10,6 +10,7 @@ import { resolveWorkspaceId } from "./bootstrap.js";import { readStitchScope, writeStitchScope } from "./config.js";import { reportAmbiguousTarget, reportResolutionFailure } from "./ui.js";import { relativePath } from "./format.js";+import { isQuiet } from "./output-shape.js";/*** The read scope for the current working directory: a co-ingested multi-repo system@@ -580,6 +581,7 @@ export function printAmbiguous(symbol: string, result: AmbiguousResult, opts?: {* Callers should skip this when format === "json" to keep JSON strict.*/export function printResolved(target: ResolvedEntity): void {+ if (isQuiet()) return;const shortId = target.id.slice(0, 8);const modeStr = target.resolutionMode !== "exact"? chalk.dim(` (${target.resolutionMode})`)diff --git a/ix-cli/src/cli/ui.ts b/ix-cli/src/cli/ui.tsindex 5a419688..95eef269 100644--- a/ix-cli/src/cli/ui.ts+++ b/ix-cli/src/cli/ui.ts@@ -11,6 +11,7 @@ import chalk from "chalk";import { llmError, llmLine } from "./llm.js";import { printJson, relativePath } from "./format.js";+import { isQuiet } from "./output-shape.js";import type { AmbiguousResult, ResolveResult, Suggestion } from "./resolve.js";// ── Brand palette ─────────────────────────────────────────────────────────────@@ -27,6 +28,7 @@ import type { AmbiguousResult, ResolveResult, Suggestion } from "./resolve.js";/** Print a bold section title preceded by a blank line. */export function renderSection(title: string): void {+ if (isQuiet()) return;console.log(chalk.bold(`\n${title}`));}@@ -66,8 +68,15 @@ export function renderBreadcrumb(// ── Alerts ────────────────────────────────────────────────────────────────────-/** Advisory hint, stale data, or informational note. */+/**+ * Advisory hint, stale data, or informational note.+ *+ * Silenced by `--quiet`. A warning is not: `renderWarning` says something is+ * wrong with the answer, and a caller asking for less output is not asking to+ * be told less about that.+ */export function renderNote(text: string): void {+ if (isQuiet()) return;console.log(` ${chalk.dim("Note")} ${chalk.dim(text)}`);}@@ -106,6 +115,7 @@ export function renderError(text: string): void {/** Print the "Resolved: kind name" header shown at the top of most command text output. */export function renderResolvedHeader(kind: string, name: string): void {+ if (isQuiet()) return;console.log(`${chalk.bold("Resolved:")} ${chalk.cyan(kind)} ${chalk.bold(name)}`);}diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex 032b1ca3..6bae94aa 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -75,6 +75,13 @@ surfaces (#575).classes — a pattern that starts with `!` is dropped rather than half-honoured.Excluded paths are counted in the ingest summary, so an exclusion is nevermistaken for a missed file.+- **`--quiet` drops the scaffolding, not the bookkeeping.** Section titles,+ `Resolved:` headers and advisory hints go; warnings, error records and the+ `shown=`/`total=`/`truncated=` fields stay. A caller asking for less output is+ not asking to be misled about what was cut.+- **`--fields name,path,lines` keeps those fields on each ROW, in that order** —+ the caller's order, not the renderer's. It never touches a header, and a field+ no row carries is dropped rather than emitted empty.- **`--pick <n>` is 1-based** everywhere it appears, and is how you resolve anambiguous target without re-running with a longer name.- **`--no-recursive` and `--no-open` negate a default-on behaviour**, so their@@ -103,6 +110,8 @@ Show methods/functions called by the given symbol (cross-file).| `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix callers <symbol>`@@ -116,6 +125,8 @@ Show methods/functions that call the given symbol (cross-file).| `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix config`@@ -151,6 +162,8 @@ List detected conflicts.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix contains <symbol>`@@ -164,6 +177,8 @@ Show members contained by the given entity (class, module, file).| `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix context [target]`@@ -183,6 +198,8 @@ Build a bounded, deterministic context bundle for a symbol, file, or entity (or| `--max-chars` | `<n>` | — | Maximum characters of evidence output; overrides `--max-tokens` (clamped to 1000-1000000) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--out` | `<path>` | — | Write the JSON bundle to this file instead of stdout || `--save` | `<id>` | — | Persist the bundle as a resumable investigation state || `--resume` | `<id>` | — | Render a saved investigation state without a backend |@@ -202,6 +219,8 @@ Show upstream dependents of the given entity (full tree by default).| `--cap` | `<n>` | `100` | Cap number of nodes visited || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--include-tests` | — | off | Include test and fixture entities in results || `--tests-only` | — | off | Show only test and fixture entities |@@ -218,6 +237,8 @@ Show diff between two revisions, optionally scoped to a file or entity.| `--full` | — | off | Return all changes (no limit) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--kind` | `<kind>` | — | Filter target entity by kind || `--path` | `<path>` | — | Restrict to symbols from files matching this path substring || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |@@ -274,6 +295,8 @@ Check Ix system health — server, database, graph integrity.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix entity <id>`@@ -283,6 +306,8 @@ Get entity details with claims and edges.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix explain <symbol>`@@ -295,6 +320,8 @@ Explain an entity — infers role, importance, and structural context.| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--raw` | — | off | Show raw metadata dump (legacy format) |### `ix help [topic]`@@ -321,6 +348,8 @@ Show provenance chain for a file or entity.| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix impact <target>`@@ -335,6 +364,8 @@ System risk analysis — what behavior is at risk if this changes.| `--limit` | `<n>` | `10` | Max top-impacted members to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix imported-by <symbol>`@@ -348,6 +379,8 @@ Show what imports the given entity.| `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix imports <symbol>`@@ -361,6 +394,8 @@ Show what the given entity imports.| `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix ingest [path]`@@ -377,6 +412,8 @@ Ingest source files or GitHub data into the knowledge graph.| `--force` | — | off | Force re-ingest even if files are unchanged (useful after parser upgrades) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--root` | `<dir>` | — | Workspace root directory || `--debug` | — | `false` | Show phase timing breakdown || `--lang` | `<langs>` | — | Comma-separated languages to include (e.g. cpp,c or typescript). Aliases: c++=cpp, c#=csharp, py=python, ts=typescript, js=javascript |@@ -399,6 +436,8 @@ List entities by kind with optional path scoping.| `--limit` | `<n>` | `50` | Max results || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix locate <symbol>`@@ -411,6 +450,8 @@ Resolve a symbol to its position in the codebase and system hierarchy.| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix map [path]`@@ -420,6 +461,8 @@ Map the architectural hierarchy of a codebase.|---|---|---|---|| `--format` | `text\|json\|llm\|silent` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--level` | `<n>` | — | Show only regions at this level (1=finest, higher=coarser) || `--min-confidence` | `<n>` | `0` | Only show regions above this confidence threshold (0-1) || `--max-items` | `<n>` | `10` | Max items to show per section in text output (default: 10) |@@ -452,6 +495,8 @@ Register `ix mcp` with the AI clients installed on this machine.| `--force` | — | `false` | Replace a registration held by a different server || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |#### `ix mcp doctor`@@ -462,6 +507,8 @@ Check that `ix mcp` is registered and launchable from each client.| `--host` | `<ids...>` | — | Only these hosts || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix overview <target>`@@ -474,6 +521,8 @@ Structural summary — what a target contains or what surrounds it.| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix patches`@@ -484,6 +533,8 @@ List recent patches.| `--limit` | `<n>` | `50` | Maximum patches to return || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix query <question>`@@ -495,6 +546,8 @@ List recent patches.| `--depth` | `shallow\|standard\|deep` | `standard` | Query depth (shallow\|standard\|deep) || `--format` | `text\|json` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--unsafe` | — | off | Enable query (can produce large outputs) |### `ix rank`@@ -511,6 +564,8 @@ Rank entities by graph-derived importance (dependents, callers, importers, membe| `--exclude-kind` | `<kinds>` | — | Comma-separated kinds to exclude from results || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix read <target>`@@ -520,6 +575,8 @@ Read raw file content, line ranges, or symbol source code.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--kind` | `<kind>` | — | Filter symbol by kind || `--path` | `<path>` | — | Restrict to symbols from files matching this path substring || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |@@ -548,6 +605,8 @@ Subcommands: `reset`.| `--model` | `opus\|sonnet\|haiku\|gpt-4o` | `opus` | Pricing model (opus\|sonnet\|haiku\|gpt-4o) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |#### `ix savings reset`@@ -568,6 +627,8 @@ Search the knowledge graph by term — ranked by structural relevance.| `--as-of` | `<rev>` | — | Search as of a specific revision || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--include-tests` | — | off | Include test and fixture entities in results || `--tests-only` | — | off | Show only test and fixture entities || `--semantic` | — | off | Use vector-similarity (embedding) search instead of keyword matching |@@ -580,6 +641,8 @@ Detect architecture smells in the codebase.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--orphan-max-connections` | `<n>` | `0` | Max connections for orphan files || `--god-module-chunks` | `<n>` | `20` | Min chunks for god module || `--god-module-fan` | `<n>` | `15` | Min fan-in/out for god module |@@ -594,6 +657,8 @@ Show graph statistics — node/edge counts by type.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) |### `ix status`@@ -603,6 +668,8 @@ Show Ix backend health and status.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--root` | `<dir>` | — | Workspace root directory |### `ix subsystems [target]`@@ -613,6 +680,8 @@ Show the persisted architectural map saved by 'ix map'.|---|---|---|---|| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--list` | — | off | List stored subsystem health scores instead of the persisted architecture map || `--detailed` | — | off | Include member files and enriched call/import edges (requires --list) || `--limit` | `<n>` | — | Max regions per page in detailed mode (default: 200 when auto-paging) |@@ -642,6 +711,8 @@ Fast lexical/text search across the codebase (uses ripgrep).| `--language` | `<lang>` | — | Filter by language (python, typescript, scala, etc.) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--root` | `<dir>` | — | Workspace root directory |### `ix trace <symbol>`@@ -660,6 +731,8 @@ Follow how it connects.| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |+| `--quiet` | — | off | Drop headers, section titles and advisory hints |+| `--fields` | `<list>` | — | Keep only these fields on each row, in this order (e.g. `name,path,lines`) || `--include-tests` | — | off | Include test and fixture entities || `--tests-only` | — | off | Show only test and fixture entities |