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 text it emits, in tokens. --max-tokens defaults to 3,000 and is converted at 2.14 characters per token, measured across 41 recorded bundles, in every output format. 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. For --format llm the budget covers the whole output: header, diagnostics, evidence rows and next lines. For json it bounds the serialized evidence list, and for text the evidence lines plus a reserve for the header; entities and relationships keep their own --max-entities and --max-relationships counts. --max-evidence defaults to 25. cl100k counts about 3.7 characters per token in llm output and 2.7 in JSON, so 2.14 keeps a bundle under its token budget; larger defaults are deferred until they are measured on ix-bench. A saved investigation records the format its budget was sized for, and --diff rebuilds with it. --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 longer than 400 lines is capped the same way. Its header adds span_end=<last line>, total_lines is the symbol’s span length (a count, not the file’s), and next=<path>:10-1327@410 resumes the symbol’s span, is capped again and carries its own next= until the symbol’s last line. --all reads the whole file or symbol.
• 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. ix trace rejects a --depth or --cap that is not a non-negative integer as a usage error. 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 directory in no workspace and no repository becomes a workspace of its own (never the default); a loose file there is ingested but registers nothing, so ix read cannot open its neighbours.
• 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).
• A registered workspace_id is never re-keyed on its own. ix map and ix ingest use the id config.yaml registers for a root, even when it differs from the id the root’s absolute path derives (sha256 of repo:<path>, 8 hex chars) – a team sharing one graph from clones at different paths, or a tool that keys on the id, pins it on purpose. The mismatch is one stderr warning per run, skipped under --silent and the machine formats; pinned: true on the workspace entry silences it for good and makes --prune-stale-workspace refuse to re-key that root (remove it first if you mean to). The CLI never writes or removes pinned. --prune-stale-workspace is the only way to switch to the path-derived id: it re-keys, re-ingests the whole workspace, and after a clean ingest deletes the old id’s graph. Before this, a mismatched id was re-keyed silently and the old id’s whole workspace deleted after the next clean ingest, on any backend.
  • Loopback only, and loopback is the URL, not ownership. The flag is refused unless the configured endpoint is loopback (localhost, 127.0.0.0/8, [::1], 0.0.0.0), because nothing on a backend records who owns a workspace id. The check cannot tell your own backend from a shared one reached through an ssh -L tunnel, kubectl port-forward or a local proxy: those pass it. Never use the flag through one.
  • The old id stays recorded until it is deleted. The re-key writes the old id and the endpoint to the workspace’s pending_prune_of in config.yaml. If the re-ingest is not clean, covers only part of the workspace (--lang, --exclude), or the delete fails, the next run with the flag against that endpoint re-ingests and retries the deletion; nothing is orphaned. It also keeps the old graph while another root in your config still uses that id. The delete refuses a redirect rather than following it. A hand-edited marker without a quoted workspace_id and an endpoint is skipped with a one-time warning, never guessed at.
  • Multi-repo systems use path ids per member. When the mapped directory holds two or more member repos, each member’s files are keyed by that member’s path-derived id, so a pinned id on the system root does not apply to them. A repo mapped both on its own (under a pinned id) and as a member of a system (under its path id) is therefore stored twice.
• 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. An auto-picked ambiguous target still prints its one-line notice on stderr (text), without the candidate list.
• --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.
• An ambiguous target is answered for its top candidate (exit 0), with an ambiguous_target notice naming the choice and listing the other candidates (llm diagnostic + candidate records, json resolutionNotices, text on stderr). A name that is no code symbol but appears in source files (a config key) is answered with up to 10 of those files, source first (llm note code=text_matches + match rows, json textMatches, plus any near-name suggestion rows); docs, changelogs and tests are not listed, and a qualified name (Class.method) stays a miss, as does any name under ix context --out / --save, ix diff and ix history, which promise a bundle, a revision diff or a history. --strict, or IX_STRICT_TARGETS=1, keeps both as errors (exit 2 and 3).
• --pick <n> is 1-based everywhere it appears, and is how you choose another candidate of an ambiguous target without re-running with a longer name. It indexes the list in its stable numbered order (best match first; equal matches dealt round-robin by file so one file cannot fill the page), and also selects among the candidates of a resolution notice (a target that resolved by choosing among equal matches; only the true ties are listed and numbered).
• --all answers an ambiguous name for every candidate (callers, callees, impact), instead of only the top one (or, under --strict, exiting 2 with the candidate list). Each row (or, for impact, each analysis) carries candidate=<n>, numbering the candidate records printed with it. It covers the tied candidates the name search returned, not only the 8 an ambiguity lists (numbered as --pick numbers them; an import of the name is skipped when a definition is listed too), up to 25 per call, so narrow with --kind or --path for a common name; a candidates_truncated diagnostic says when the cap or the search cut it off. --pick takes precedence over it.
• Exit codes for the graph commands: 0 results (an ambiguous target answered for its top candidate, or a name answered with its text matches, included), 2 ambiguous under --strict / IX_STRICT_TARGETS=1 (candidates listed; also without it for a --pick past the end, or a name only fuzzy matches carry and no source file mentions), 3 not found anywhere (suggestions and a reason when known), 4 workspace not mapped, 1 any other error. IX_LEGACY_EXIT_CODES=1 makes every non-zero exit 1 again. With several targets (ix locate a b c) the run exits with the worst target’s code and each group carries its own.
• --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.

Each symbol’s tests are the ones the graph links to it. Test files that import the target file (local Python package imports, JS/TS relative imports) or follow its naming convention are file-level evidence: one that agrees with a graph test adds to that row’s sources (graph, import, naming) and ranks it first; the rest are listed once for the file (fileTests in json, file_test rows in llm), not under each symbol. A name counts only when no same-named file is as near the test.

Flag	Value	Default	Effect
--limit	<n>	text/llm: 8 callers, 5 others; json: all	Max rows per list; 0 for all. Explicit limits apply to callers, users, tests, file-level tests and non-test importer rows. Text/llm remain subject to --budget
--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)
--all	—	off	When the symbol is ambiguous, answer for every candidate; rows are tagged with their candidate
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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 <symbols...>

Show methods/functions that call the given symbols (cross-file). Several symbols answer in one call, grouped per symbol. For a Java method, callers through a superclass or interface follow the direct ones, tagged via=<Supertype>.<method> (json: via).

Flag	Value	Default	Effect
--kind	<kind>	—	Filter target entity by kind
--path	<path>	—	Restrict to symbols from files matching this path substring
--no-suggest	—	off	Disable did-you-mean candidates on unresolved targets
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--all	—	off	When the symbol is ambiguous, answer for every candidate; rows are tagged with their candidate
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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, build output, imports, generated files such as @generated/DO NOT EDIT headers and *_pb2.py, and docs/examples/site directories excluded unless packaging or an __init__.py makes them importable), builds the bundle around the first, and adds a rankedFiles list: BM25 against the issue text, starting files boosted by up to 10% of the best BM25 score (snippet-only names get no boost; a file the issue names always stays in the list), nudged by graph closeness, then up to 3 companion files (a co-change, re-export or issue-named import of a leading file, marked companion; not in --lean). Companions are best effort within a short time budget, so a slow or cold git log can leave them out; the rest of the list does not depend on timing. 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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command. A named target only; the fresh side of --diff rebuilds the saved entity by its id, and re-resolves the name strictly only when that id is gone or --kind/--path/--pick is given
--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	Token budget for the printed output (llm: all of it; json and text: the evidence) (clamped to 500-200000)
--max-chars	<n>	—	Character budget for the printed output (llm: all of it; json and text: the evidence); 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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command

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
--no-suggest	—	off	Disable did-you-mean candidates on unresolved targets
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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
--no-suggest	—	off	Disable did-you-mean candidates on unresolved targets
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--all	—	off	When the target is ambiguous, analyse every candidate; each analysis is tagged with its candidate
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--depth	<n>	1	Expansion depth for callers/importers (default 1, max 3)
--limit	<n>	10	Max top-impacted members (and llm caller/callee rows) to show; JSON lists are 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
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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)
--prune-stale-workspace	—	off	Re-key a workspace whose registered id is not its path-derived id, and delete the old id’s graph after a clean ingest. Loopback endpoints only – and loopback is the URL, not ownership: never use it through a tunnel or proxy to a shared backend

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
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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 <symbols...>

Resolve symbols to their position in the codebase and system hierarchy. Several symbols answer in one call, grouped per symbol.

Flag	Value	Default	Effect
--kind	<kind>	—	Filter target entity by kind
--path	<path>	—	Restrict to results from files matching this path substring
--no-suggest	—	off	Disable did-you-mean candidates on unresolved targets
--pick	<n>	—	Pick Nth candidate from ambiguous results (1-based)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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)
--remap	—	off	Compute the map now, even from an automatic (hook) run that would defer it
--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)
--prune-stale-workspace	—	off	Re-key a workspace whose registered id is not its path-derived id, and delete the old id’s graph after a clean ingest. Loopback endpoints only – and loopback is the URL, not ownership: never use it through a tunnel or proxy to a shared backend

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 overrides <symbols...>

Alias: ix implementations. Show the other definitions of a method: what it overrides or implements, its overrides, and sibling implementations. Read from the graph’s EXTENDS (extends and implements) and CONTAINS edges and matched by name, up to 5 levels each way and 32 types; a free function answers with no rows and no_owner_type. Several symbols answer in one call, grouped per symbol.

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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--limit	<n>	50	Max results to show
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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 or symbol, past the 400-line default cap

An ambiguous file or symbol name exits 0 with an ambiguous record and its candidates (unlike the graph commands’ exit 2); retry with --pick <n> or --path. A miss exits 3.

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 workspace id the registered workspace containing cwd uses (/v1/reset/workspace); other ids are left alone, but anyone else who registered the same id (a shared, pinned workspace) loses that graph too. 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
--limit	<n>	50 (text/llm); all (json)	Max candidates, highest confidence first; 0 = all, unfiltered. Otherwise non-source orphan files (docs, templates, data) are dropped before the cut. With --list, caps the stored claims (all when omitted)
--wait	<seconds>	20 (json/llm); 300 (text)	How long to wait for a fresh analysis, at most 300 (the HTTP client stops waiting for an answer after 5 minutes). IX_SMELLS_WAIT (whole seconds, capped at 300; ignored under MCP) sets it too; the flag wins. Past it, or when the backend refuses to run analysis (403), the stored results are shown instead, marked stale (exit 0); with none stored, the error stands (exit 1). Text prints a progress line on stderr every 10 s when stderr is a terminal. --wait 120 restores the 2-minute wait json/llm had before

A stale answer is the stored claims shaped as a fresh run’s output (file, smell, confidence, signals per candidate, plus the claim’s entity_id), with the same non-source filter, ranking and cap. JSON adds stale: true, computed_rev and computed_at (the newest rev a stored claim carries and its run_at; null when the backend does not store them, as today’s do not) and diagnostics: [{code: "smells_stale", reason: "timeout" | "not_permitted", message}]; truncated is also true when the backend returned only part of its stored claims. llm prints one diagnostic code=smells_stale record after the header, and each row carries its claim’s entity; text leads with a Stale: line. The CLI stops waiting but cannot tell whether the backend goes on, so a stale answer never claims a refresh is running.

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
--offset	<n>	0	Skip the first N results (use the next: hint to page)
--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)
--strict	—	off	Report an ambiguous target (exit 2) or a name found only as text (exit 3) as an error instead of answering it; IX_STRICT_TARGETS=1 does the same for every command
--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 verify [paths...]

Compare the graph’s nodes to a fresh re-parse of a sample of files. Nodes only: edges are not compared yet.

Flag	Value	Default	Effect
--sample	<n>	20 (or the number of paths given)	How many files to check: named paths first, then files the last map could not apply, then the most recently changed, then a seeded random pick
--seed	<n>	24	Seed for the random part of the sample; the same seed checks the same files
--root	<dir>	—	Workspace root directory
--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 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