Flag reference

Every flag the open-source CLI registers, command by command. For which command answers which question, start with the command reference. ix <command> --help prints the same flags from the CLI.

This page is generated from the registered command tree, so it matches what the CLI accepts.

How to read the tables

• Value — — for a boolean switch, otherwise the placeholder the command takes, or the accepted choices when it validates them. A value outside a choice list is rejected, not silently ignored: error: option '--format <fmt>' argument 'yaml' is invalid. Allowed choices are text, json, llm.
• Default — the value in force when the flag is absent. off for a boolean, — when the command has no default and treats absence as “unset” (which is not always the same as zero).
• Both --format and -y/--yes style short forms are shown as --long / -s where one exists.
• Pro commands (plan, task, goal, decide, bug, briefing, workflow, …) are not here: this file covers what registerOssCommands registers. See output-formats.md for the Pro surface.

Flags with behaviour worth knowing

• ix diff refuses conflicting volume flags rather than picking a winner. --summary ignores both --limit and --full, and --full --limit is rejected on its own; each combination errors with which flag to drop.
• ix reset is global. --code narrows what kind of data goes, not which workspace — see the Gotchas section of commands.md before running it in a shared backend. --workspace is the one that narrows which workspace: only the registered one containing cwd.
• --detailed on ix subsystems requires --list, and the reverse constraint bites harder: --limit, --offset, --regions, --edge-cap and --member-file-cap all require --detailed, so ix subsystems --list --limit 50 exits with an error rather than a shorter list. --detailed auto-paginates on its own; --offset or --regions turns that off, and --limit only sets the page size.
• ix context budgets the evidence block in tokens, not characters. --max-tokens defaults to 3,000 and is converted at 2.14 characters per token, measured across 41 recorded bundles. At 1,500 the evidence block held about ten items, and for a file target those were its own members: ix-bench agents were shown 0.59 of the expected files ix had found, against all of them at 3,000, for about 320 more tokens. --max-chars is still there for a caller who needs exact bytes and overrides it; passing both is refused rather than silently ranked, because the output does not say which one won.
• ix mcp advertises five tools by default, not twenty-six: ix_context, ix_search, ix_neighbors, ix_impact and ix_read, one per question the graph answers better than Grep/Read. ix_neighbors{relation} replaces ix_callers / ix_callees / ix_imports / ix_imported_by, whose schemas differed by one word; ix_health, ix_text, ix_locate, ix_overview and ix_explain moved to --tools=all, which advertises every tool. The Pro tools are offered under both whenever Pro is installed. The server also sends instructions in initialize (when to use Ix over Grep, and which tool first), which hosts that defer tool schemas still show the model. Over MCP, hints and next records are phrased as tool calls (ix_neighbors symbol=X relation=callers), never as CLI flags.
• ix read <file> stops at 400 lines. The header then carries truncated=true total_lines=<n> next=<path>:401-800, so the next page is one command away. A line range you typed (ix read a.ts:1-900) is never capped, a symbol target is its own span, and --all reads the whole file.
• ix depends and ix trace stop at depth 3 and 100 nodes. Both were unbounded, which on a hub is thousands of nodes the caller pays for before seeing any. The output distinguishes the two ways a walk ends: truncated=true means the node cap dropped nodes, depth_limited=true means the walk stopped descending and there may or may not be more. JSON carries them per direction in each summary. When ix trace --to finds no route, a search a bound cut short adds the same code after no_path; a bare no_path means the whole reachable graph was searched. --depth and --cap take anything. When the cap cuts a depends or directional trace walk, the nodes kept are the shallowest: every node at depth d before any at depth d+1, so the first level is complete before the second begins. (The walk used to be depth-first, and could spend the whole cap down its first branch.) A walk the cap does not cut is the same tree it always was.
• ix ingest <path> writes to the workspace the path belongs to – the registered workspace containing it, else its git repository – and a file or directory inside it refreshes just that part, leaving the rest of the workspace alone. Only a path in no workspace and no repository becomes a workspace of its own.
• ix ingest <path> coalesces with a running ix map or ix ingest of the same workspace, as ix map does: it does not run beside the holder, asks it for one more pass, and exits 0 (or IX_MAP_COALESCE_EXIT_CODE). With --format json it prints {"coalesced": true, "workspace": <root>}. The holder runs the extra pass before it exits: ix map re-ingests the workspace, and so does ix ingest once the workspace has a baseline (otherwise it re-ingests only its own path).
• ix ingest honours --exclude <glob> and a .ixignore at the workspace root, matched relative to that root. A deliberate subset of .gitignore: # comments, *, ?, **, a leading / to anchor at the root, a trailing / for directories only, and a bare name matching at any depth. No ! negation and no character classes — a pattern that starts with ! is dropped rather than half-honoured. Excluded paths are counted in the ingest summary, so an exclusion is never mistaken 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 an ambiguous target without re-running with a longer name.
• --no-recursive and --no-open negate a default-on behaviour, so their Default of on is the positive behaviour, and passing the flag turns it off.

Commands

ix (root)

Options declared on the program itself rather than on any subcommand. They work before a command name — ix --version, not ix map --version.

Flag	Value	Default	Effect
--version	—	off	Print the CLI version and exit (-V)

ix around <target>

Show who depends on the code at a file location: callers, importers, tests. <target> is path[:line[-end]], relative to the workspace root or absolute.

Flag	Value	Default	Effect
--limit	<n>	8	Max rows per list (callers; users, tests and importers cap at 5)
--budget	<tokens>	300	Token budget for text/llm output (~4 chars a token); rows are cut to fit, totals are kept. json is not cut
--format	text|json|llm	text	Output format — see 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 (text: the importer rows)
--fields	<list>	—	Keep only these fields on each row, in this order (e.g. name,path,lines)

ix callees <symbol>

Show methods/functions called by the given symbol (cross-file).

Flag	Value	Default	Effect
--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)
--limit	<n>	50	Max results to show
--format	text|json|llm	text	Output format — see 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>

Show methods/functions that call the given symbol (cross-file).

Flag	Value	Default	Effect
--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)
--limit	<n>	50	Max results to show
--format	text|json|llm	text	Output format — see 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

Show or update Ix configuration.

Subcommands: show, get, set, prune.

No flags.

ix config show

Show current configuration. Values of keys that look like credentials (token, secret, jwt, password) print as (redacted).

No flags.

ix config get <key>

Get a config value (e.g. endpoint, user.name).

No flags.

ix config set <key> <value>

Set a config value (e.g. ix config set user.name ‘Alice’). endpoint must be an http:// or https:// URL; workspaces cannot be set by hand.

No flags.

ix config prune

Remove registered workspaces whose directory no longer exists. Their graphs stay in the backend.

Flag	Value	Default	Effect
--dry-run	—	off	List what would be removed without changing anything

ix conflicts

List detected conflicts.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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>

Show members contained by the given entity (class, module, file).

Flag	Value	Default	Effect
--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)
--limit	<n>	50	Max results to show
--format	text|json|llm	text	Output format — see 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]

Build a bounded, deterministic context bundle for a symbol, file, or entity (or resume/diff a saved investigation without a target).

Flag	Value	Default	Effect
--from-issue	<file>	—	Start from an issue or bug report instead of a target: a file, or - for stdin. Resolves the paths and code names it mentions to up to 3 definitions (tests, docs, build output and imports excluded), builds the bundle around the first, and adds a rankedFiles list: starting files first, then BM25 against the issue text, nudged by graph closeness. Falls back to the best BM25 file when nothing resolves. Not combinable with a target, --kind, --path, --pick or --diff
--lean	—	off	With --from-issue: only the starting points Ix trusts (a path the issue names, or a specific identifier) as path:lines with why, then the next 4 files by the issue’s text — about 150 tokens instead of a full bundle. When it trusts none (a BM25 fallback, or only common words like debug resolved), one line saying so. Not combinable with --save or --out
--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)
--depth	compact|standard|full|shallow|deep	—	Context-graph expansion depth (compact|standard|full|shallow|deep)
--as-of-rev	<n>	—	Historical context as of a graph revision
--max-entities	<n>	—	Maximum entities in the bundle (default: 50, clamped to 1-500)
--max-relationships	<n>	—	Maximum relationships in the bundle (default: 100, clamped to 1-1000)
--max-evidence	<n>	—	Maximum evidence items in the bundle (default: 25, clamped to 1-200)
--max-tokens	<n>	3000	Maximum tokens of evidence output (clamped to 500-200000)
--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
--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
--diff	<id>	—	Diff a saved investigation against a fresh build of the same target
--list	—	off	List saved investigations (no target, no backend)

ix depends <symbol>

Show upstream dependents of the given entity (full tree by default).

Flag	Value	Default	Effect
--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)
--depth	<n>	3	Cap traversal depth
--cap	<n>	100	Cap number of nodes visited
--format	text|json|llm	text	Output format — see 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

ix diff <fromRev> <toRev> [target]

Show diff between two revisions, optionally scoped to a file or entity. The diff covers the workspace the current directory belongs to; --all covers every workspace on the backend (outside any mapped workspace it does anyway).

Flag	Value	Default	Effect
--entity	<id>	—	Filter by entity ID (deprecated, use positional target)
--summary	—	off	Show compact summary only (server-side, fast)
--content	—	off	Show detailed attribute changes for each entity
--limit	<n>	—	Max changes to return (default 100)
--full	—	off	Return all changes (up to the backend’s maximum, 5000)
--all	—	off	Diff every workspace on the backend, not just this one
--format	text|json|llm	text	Output format — see 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)

ix docker

Manage the IX backend Docker containers.

Subcommands: start, stop, status, logs, restart.

No flags.

ix docker start

Start the IX backend (ArangoDB + Memory Layer).

Flag	Value	Default	Effect
--local-token	—	off	Require a bearer token on the backend; the CLI stores and sends it
--no-local-token	—	—	Stop requiring the token and forget the stored one

ix docker stop

Stop the IX backend containers.

Flag	Value	Default	Effect
--remove-data	—	off	Also remove the current project’s ArangoDB data volume
--remove-all-data	—	off	Remove all local Ix ArangoDB data volumes across repos
--yes	—	off	Skip confirmation prompt (for use with –remove-all-data)

ix docker status

Show backend container and health status.

No flags.

ix docker logs

Tail backend container logs.

Flag	Value	Default	Effect
--follow / -f	—	true	Follow log output

ix docker restart

Restart the IX backend containers.

No flags.

ix doctor

Check Ix system health — server, database, graph integrity.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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>

Get entity details with claims and edges.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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>

Explain an entity — infers role, importance, and structural context.

Flag	Value	Default	Effect
--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)
--format	text|json|llm	text	Output format — see 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]

Additional help topics. With no topic, prints the top-level help. workflows (or workflow) and advanced are prose topics; any other topic is looked up as a registered command and shows that command’s help. The retired plurals goals and bugs forward to goal and bug — but that only pays off with Ix Pro installed. On OSS both are registerProStubs placeholders carrying no subcommands, so ix help bugs prints Usage: ix bug [options] [args...] and its -h line, and nothing about ix bug list. An unrecognised topic exits non-zero.

No flags.

ix history <target>

Show provenance chain for a file or entity.

Flag	Value	Default	Effect
--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)
--format	text|json|llm	text	Output format — see 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 hook

Entry points an agent harness runs on its own events; not typed by hand. One subcommand per (harness, event), since each has its own stdin/stdout contract.

No flags.

ix hook claude-post-edit

Claude Code PostToolUse hook, matcher Edit|MultiEdit|Write|Bash. Reads the hook JSON on stdin and the working tree’s git diff -U0 HEAD, so an edit made through a Bash script counts as much as one made with Edit or Write; each hunk’s old side locates the edited symbols in HEAD’s text, which is what the graph indexed. Prints {"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"..."}} naming the changed symbols’ callers, importers that use them, and tests that reach them – each symbol once per session (state per session_id in IX_HOOK_STATE_DIR, default <IX_HOME>/hook-state, dropped after a week unused). A call whose diff is empty or unchanged since the last report answers from one git call, without loading the CLI. Always exits 0; any failure (backend down, unmapped workspace, file not in the graph, non-code or untracked file, IX_HOOK_TIMEOUT_MS, default 3000, exceeded) prints nothing. Outside a git repository it falls back to the Edit/Write tool’s own patch. IX_HOOK_DEBUG=1 says why on stderr; IX_HOOK_LOG=<file> appends one JSON line per call with what it did (no_changes, diff_unchanged, reported, silent, timeout; tool-edit outside git) and why.

Flag	Value	Default	Effect
--graph-root	<dir>	—	Mapped workspace to query (default: the one containing the edited file)
--worktree	<dir>	—	Checkout the agent edits (default: the git root of the hook’s cwd); its paths map to the same relative paths in --graph-root
--budget	<tokens>	300	Token budget for the context it adds (~4 chars a token)

ix impact <target>

System risk analysis — what behavior is at risk if this changes.

Flag	Value	Default	Effect
--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)
--depth	<n>	1	Expansion depth for callers/importers (default 1, max 3)
--limit	<n>	10	Max top-impacted members to show
--format	text|json|llm	text	Output format — see 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>

Show what imports the given entity.

Flag	Value	Default	Effect
--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)
--limit	<n>	50	Max results to show
--format	text|json|llm	text	Output format — see 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>

Show what the given entity imports.

Flag	Value	Default	Effect
--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)
--limit	<n>	50	Max results to show
--format	text|json|llm	text	Output format — see 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]

Ingest source files or GitHub data into the knowledge graph.

Flag	Value	Default	Effect
--path	<dir>	—	Path to ingest (alternative to positional argument)
--no-recursive	—	on	Do not recurse into subdirectories (recursive is on by default)
--github	<owner/repo>	—	Ingest issues, PRs, and commits from a GitHub repository
--token	<pat>	—	GitHub personal access token
--since	<date>	—	Only fetch items updated after this date (ISO 8601)
--limit	<n>	50	Max items per category (default 50)
--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
--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
--exclude	<glob>	—	Exclude paths matching this glob (repeatable; same syntax as .ixignore)

ix init

(deprecated) Initialize Ix — use ix map . instead.

No flags.

ix inventory

List entities by kind with optional path scoping.

Flag	Value	Default	Effect
--kind	<kind>	—	Entity kind to list (class, method, function, file, module, etc.)
--path	<path>	—	Filter by source file path substring
--limit	<n>	50	Max results
--format	text|json|llm	text	Output format — see 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>

Resolve a symbol to its position in the codebase and system hierarchy.

Flag	Value	Default	Effect
--kind	<kind>	—	Filter target entity by kind
--path	<path>	—	Restrict to results from files matching this path substring
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--format	text|json|llm	text	Output format — see 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]

Map the architectural hierarchy of a codebase.

Flag	Value	Default	Effect
--format	text|json|llm|silent	text	Output format — see 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)
--all-items	—	off	Show all items in each section (overrides –max-items)
--sort	importance|confidence|size|alpha	importance	Sort mode for text output (importance|confidence|size|alpha)
--graph	—	off	Render the hierarchy as a graph/tree view (default)
--list	—	off	Render the ranked list view instead of the default graph/tree view
--full	—	off	Force full local map, bypassing automatic safety limits (advanced/testing)
--verbose	—	off	Show raw confidence/crosscut scores and signals, plus per-file ingest diagnostics (including why a patch failed to commit)
--silent	—	off	Suppress all output except a one-line summary (useful for LLM hooks)

ix mcp

Serve Ix tools over the Model Context Protocol (stdio).

Subcommands: install, doctor.

Flag	Value	Default	Effect
--tools	core|all	core	Which catalog to advertise — five tools, or every one

ix mcp install

Register ix mcp with the AI clients installed on this machine.

Flag	Value	Default	Effect
--host	<ids...>	—	Only these hosts (claude, codex, cursor, vscode, gemini, openclaw, opencode)
--dry-run	—	false	Report what would change without writing anything
--force	—	false	Replace a registration held by a different server
--format	text|json|llm	text	Output format — see 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

Check that ix mcp is registered and launchable from each client.

Flag	Value	Default	Effect
--host	<ids...>	—	Only these hosts
--format	text|json|llm	text	Output format — see 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>

Structural summary — what a target contains or what surrounds it.

Flag	Value	Default	Effect
--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)
--format	text|json|llm	text	Output format — see 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

List recent patches.

Flag	Value	Default	Effect
--limit	<n>	50	Maximum patches to return
--format	text|json|llm	text	Output format — see 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>

[DEPRECATED] Broad NLP-style graph query — prefer bounded commands instead.

Flag	Value	Default	Effect
--as-of	<rev>	—	Time-travel to a specific revision
--depth	shallow|standard|deep	standard	Query depth (shallow|standard|deep)
--format	text|json	text	Output format — see 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

Rank entities by graph-derived importance (dependents, callers, importers, members).

Flag	Value	Default	Effect
--by	<metric>	—	Metric to rank by (dependents, callers, importers, members)
--kind	<kind>	—	Entity kind to rank (e.g. class, method, module)
--top	<n>	10	Number of results to return
--path	<path>	—	Filter entities by source path substring
--exclude-path	<path>	—	Exclude entities whose source path contains this substring
--exclude-kind	<kinds>	—	Comma-separated kinds to exclude from results
--format	text|json|llm	text	Output format — see 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>

Read raw file content, line ranges, or symbol source code.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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)
--root	<dir>	—	Workspace root directory
--all	—	off	Read the whole file, past the 400-line default cap

ix reset

Wipe graph data.

Flag	Value	Default	Effect
--yes / -y	—	off	Skip confirmation prompt
--code	—	off	Reset only code graph (files, functions, classes, regions); preserve goals, plans, tasks, bugs, and decisions
--ingest	—	off	Re-run ix map after wiping (rebuilds the code graph)
--workspace	—	off	Reset only the registered workspace containing cwd (/v1/reset/workspace); every other workspace is left alone. The fix for a hollowed graph, with --ingest

ix savings

Show token savings from Ix usage.

Subcommands: reset.

Flag	Value	Default	Effect
--detail	—	off	Include per-command breakdown
--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
--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

Reset lifetime savings totals.

No flags.

ix search <term>

Search the knowledge graph by term — ranked by structural relevance.

Flag	Value	Default	Effect
--limit	<n>	10	Max results
--kind	<kind>	—	Filter and boost results by node kind (e.g. class, function, decision)
--language	<lang>	—	Filter by language/file extension (e.g. scala, ts)
--path	<path>	—	Filter results by file path (case-insensitive substring match). Keyword searches widen the candidate window up to 2000 nodes and warn if that bound is reached.
--as-of	<rev>	—	Search as of a specific revision
--format	text|json|llm	text	Output format — see 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

ix smells

Detect architecture smells in the codebase.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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
--weak-max-neighbors	<n>	1	Max neighbors for weak component
--list	—	off	List existing smell claims without rerunning

ix stats

Show graph statistics — node/edge counts by type.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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

Show Ix backend health and status.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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]

Show the persisted architectural map saved by ‘ix map’.

Flag	Value	Default	Effect
--format	text|json|llm	text	Output format — see 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)
--offset	<n>	—	Skip N regions in detailed mode (disables auto-pagination)
--regions	<list>	—	Comma-separated region IDs or names to scope detailed listing
--edge-cap	<n>	—	Max edges per direction per region in detailed mode
--member-file-cap	<n>	—	Max member files per region in detailed mode
--target	<target>	—	Scope subsystem output to a persisted architecture region
--pick	<n>	—	Resolve an ambiguous region target by numbered candidate
--level	<n>	—	Filter to level (1=module, 2=subsystem, 3=system)
--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)
--all-items	—	off	Show all items in each section (overrides –max-items)
--sort	importance|confidence|size|alpha	importance	Sort mode for text output (importance|confidence|size|alpha)
--graph	—	off	Render the hierarchy as a graph/tree view instead of the default ranked list
--verbose	—	off	Show raw confidence scores, crosscut scores, boundary ratios, and signals
--explain	—	off	Explain a scoped subsystem region in plain English

ix text <term>

Fast lexical/text search across the codebase (uses ripgrep).

Flag	Value	Default	Effect
--limit	<n>	20	Max results
--path	<dir>	.	Restrict search to a workspace-relative directory
--language	<lang>	—	Filter by language (python, typescript, scala, etc.)
--format	text|json|llm	text	Output format — see 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>

Follow how it connects.

Flag	Value	Default	Effect
--to	<target>	—	Find path to target symbol
--upstream	—	off	Show who calls/imports this (same as depends)
--downstream	—	off	Show what this calls/imports (outward flow)
--kind	<kind>	—	Relationship kind: calls|imports|depends|contains
--depth	<n>	3	Cap traversal depth in edges (also applies to --to)
--cap	<n>	100	Cap nodes visited per direction, or across the --to search (including the source)
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--path	<path>	—	Restrict to symbols from files matching this path substring
--format	text|json|llm	text	Output format — see 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

ix upgrade

Upgrade ix CLI, backend, and components to the latest version.

Flag	Value	Default	Effect
--check	—	off	Only check for updates, don’t install

ix view

Open the Ix System Compass visualizer.

Subcommands: start, stop, status.

Flag	Value	Default	Effect
--port / -p	<port>	8080	Port to serve on

ix view start

Start the visualizer (default).

Flag	Value	Default	Effect
--no-open	—	on	Don’t auto-open browser
--all	—	off	Show every ingested workspace together (no workspace scoping)

ix view stop

Stop the visualizer.

No flags.

ix view status

Show visualizer status.

No flags.

ix watch

Watch files and auto-ingest on changes.

Flag	Value	Default	Effect
--path	<path>	—	Restrict watching to a subdirectory
--root	<dir>	—	Workspace root directory