Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
Ix Flag Reference
Every flag the OSS CLI registers, per command. Load this when you need a flag that commands.md does not show — that file routes a goal to a command and stays deliberately short, and the flags that shape the answer live here.
Generated from the registered command tree, not written by hand:
cd ix-cli && npm run build
node scripts/dump-cli-surface.mjs # full JSON, one object per command
node scripts/dump-cli-surface.mjs --flags # one "<command>\t<flag>" pair per line, sorted
That script is the reason this file can be trusted: the previous state of the docs covered 27 of the 76 implemented flags, because nothing connected the two surfaces (#575).
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.
offfor a boolean,—when the command has no default and treats absence as "unset" (which is not always the same as zero). - Both
--formatand-y/--yesstyle short forms are shown as--long/-swhere one exists. - Pro commands (
plan,task,goal,decide,bug,briefing,workflow, ...) are not here: this file covers whatregisterOssCommandsregisters. See output-formats.md for the Pro surface.
Flags with behaviour worth knowing
ix diffrefuses conflicting volume flags rather than picking a winner.--summaryignores both--limitand--full, and--full --limitis rejected on its own; each combination errors with which flag to drop.ix resetis global.--codenarrows what kind of data goes, not which workspace — see the Gotchas section of commands.md before running it in a shared backend.--workspaceis the one that narrows which workspace: only the registered one containing cwd.--detailedonix subsystemsrequires--list, and the reverse constraint bites harder:--limit,--offset,--regions,--edge-capand--member-file-capall require--detailed, soix subsystems --list --limit 50exits with an error rather than a shorter list.--detailedauto-paginates on its own;--offsetor--regionsturns that off, and--limitonly sets the page size.ix contextbudgets the text it emits, in tokens.--max-tokensdefaults 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 llmthe budget covers the whole output: header, diagnostics, evidence rows andnextlines. Forjsonit bounds the serialized evidence list, and for text the evidence lines plus a reserve for the header; entities and relationships keep their own--max-entitiesand--max-relationshipscounts.--max-evidencedefaults 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--diffrebuilds with it.--max-charsis 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 mcpadvertises five tools by default, not twenty-six:ix_context,ix_search,ix_neighbors,ix_impactandix_read, one per question the graph answers better than Grep/Read.ix_neighbors{relation}replacesix_callers/ix_callees/ix_imports/ix_imported_by, whose schemas differed by one word;ix_health,ix_text,ix_locate,ix_overviewandix_explainmoved to--tools=all, which advertises every tool. The Pro tools are offered under both whenever Pro is installed. The server also sendsinstructionsininitialize(when to use Ix over Grep, and which tool first), which hosts that defer tool schemas still show the model. Over MCP, hints andnextrecords 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 carriestruncated=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 addsspan_end=<last line>,total_linesis the symbol's span length (a count, not the file's), andnext=<path>:10-1327@410resumes the symbol's span, is capped again and carries its ownnext=until the symbol's last line.--allreads the whole file or symbol.ix dependsandix tracestop 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=truemeans the node cap dropped nodes,depth_limited=truemeans the walk stopped descending and there may or may not be more. JSON carries them per direction in eachsummary. Whenix trace --tofinds no route, a search a bound cut short adds the same code afterno_path; a bareno_pathmeans the whole reachable graph was searched.ix tracerejects a--depthor--capthat is not a non-negative integer as a usage error. When the cap cuts adependsor directionaltracewalk, 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, soix readcannot open its neighbours.ix ingest <path>coalesces with a runningix maporix ingestof the same workspace, asix mapdoes: it does not run beside the holder, asks it for one more pass, and exits 0 (orIX_MAP_COALESCE_EXIT_CODE). With--format jsonit prints{"coalesced": true, "workspace": <root>}. The holder runs the extra pass before it exits:ix mapre-ingests the workspace, and so doesix ingestonce the workspace has a baseline (otherwise it re-ingests only its own path).ix ingesthonours--exclude <glob>and a.ixignoreat 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.--quietdrops the scaffolding, not the bookkeeping. Section titles,Resolved:headers and advisory hints go; warnings, error records and theshown=/total=/truncated=fields stay. A caller asking for less output is not asking to be misled about what was cut.--fields name,path,lineskeeps 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. 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).--allanswers an ambiguous name for every candidate (callers,callees,impact), instead of exiting 2 with the candidate list. Each row (or, forimpact, each analysis) carriescandidate=<n>, numbering thecandidaterecords printed with it. It covers the tied candidates the name search returned, not only the 8 an ambiguity lists (numbered as--picknumbers them; an import of the name is skipped when a definition is listed too), up to 25 per call, so narrow with--kindor--pathfor a common name; acandidates_truncateddiagnostic says when the cap or the search cut it off.--picktakes precedence over it.- Exit codes for the graph commands:
0results,2ambiguous (candidates listed),3not found (suggestions and a reason when known),4workspace not mapped,1any other error.IX_LEGACY_EXIT_CODES=1makes every non-zero exit1again. With several targets (ix locate a b c) the run exits with the worst target's code and each group carries its own. --no-recursiveand--no-opennegate a default-on behaviour, so their Default ofonis 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) |
--all |
— | off | When the symbol is ambiguous, answer for every candidate; rows are tagged with their candidate |
--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 |
--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 |
--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) |
--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, 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 |
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) |
--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) |
--all |
— | off | When the target is ambiguous, analyse every candidate; each analysis is tagged with its candidate |
--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) |
--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) |
--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) |
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 |
--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) |
--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) |
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 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 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 |
--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) |
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) |
--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 |