CLI Reference

Global flags

These flags work on any subcommand (they are declared global = true).

ig search

The primary command. Searches for regex patterns across indexed files. Auto-builds the index on first run, and rebuilds it inline whenever it is stale.

ig [OPTIONS] <PATTERN> [PATH]
ig search [OPTIONS] <PATTERN> [PATH]  # also works

BM25 ranking — --top N v1.10.0

Regex search returns every match in filesystem order. --top N scores each matched file with Okapi BM25 and keeps only the N highest-ranked, so the agent sees the files that implement the concept — not the files that merely mention it in a comment.

$ ig --top 5 useState
apps/.../create-conversational/vehicle-edit-step-dialog.tsx
  3: import { useState, useMemo } from "react";
 73:   const [value, setValue] = useState(formData.saleMode);
107:   const [brandId, setBrandId] = useState(formData.brand);
 …
(top-5 returns 3 KB instead of the 15 KB flat compressed output)

Formula: score = idf · (tf · (k1+1)) / (tf + k1 · (1 − b + b · dl / avdl)) with k1 = 1.5, b = 0.75. tf is the match count, dl is the file byte-size, avdl is the mean across the result set. Overhead: one stat(2) per candidate, negligible.

Semantic query expansion — --semantic v1.10.0

Learn synonyms from the corpus itself, no ML model, no download. During ig index, a second pass tokenises every line and counts co-occurrences in a 5-line sliding window; at finalisation we rank each token's top-10 neighbours by count-weighted PPMI and persist a cooccurrence.bin file alongside the index in the XDG cache (~1.5 MB on a 3K-file repo).

$ ig --semantic --top 5 throw
(semantic: expanded 'throw' → got, inattendu, denied, autorisé, trouvée, manquant)
apps/packages/reader-api-vo/scripts/test-rest-e2e.ts
 44:   throw new Error("HTTP server did not become ready in time");
114:     throw new Error(`${label} should be an array`);
 …
# finds literal throws AND French exception messages, in one pass

Theoretical basis: Levy & Goldberg (NeurIPS 2014) proved skip-gram word2vec with negative sampling implicitly factorises the shifted-PMI matrix — direct PMI recovers most of the embedding neighbourhood quality at a fraction of the cost and with none of the model dependency.

Controls:

• Disable the second index pass entirely: IG_SEMANTIC=0 ig index
• Opt-out per query: just don't pass --semantic
• Inspect what was added: the stderr line (semantic: expanded 'x' → …) shows every term included

Expansion quality depends on how often the term co-occurs with others in your corpus: throw, payment, auth, config work well; rare terms may get a weak or empty expansion.

# Basic regex search
ig "async fn \w+" src/

# Case-insensitive with 2 lines of context
ig -i -C 2 "TODO" .

# JSON output for AI agents
ig --json "impl \w+ for" src/

# Only Rust files
ig --type rs "pub fn" .

# Files matching glob
ig --glob 'src/**/*.rs' "Result<" .

# Show stats (candidates filtered, time)
ig --stats "use std" .

ig index

Build or rebuild the sparse n-gram index for a directory. The index is written under ~/.cache/ig/projects/<hash>/ (XDG cache; ~/Library/Caches/ig/ on macOS) — never inside the repo. ig search calls this automatically when no index exists or the index is stale, so you rarely run it by hand.

ig index [PATH]   # default: current directory

# Index current directory
ig index

# Index specific path
ig index /path/to/project

ig status

Display statistics about the current index — file count, index size, n-gram count, version, and last build time. Use ig cache-ls to list every cached project.

ig status .

instant-grep index status
──────────────────────────
Location:    ~/.cache/ig/projects/2e0c.../
Version:     13
Files:       1,552
N-grams:     48,392
Lexicon:     31 MB
Postings:    7.1 MB
Metadata:    111 KB
Built:       2026-05-20 10:12:08

ig files

List all project files, respecting .gitignore and default exclusions. Ideal for AI agents needing a file inventory before deciding what to read.

ig files [OPTIONS] [PATH]

# List all project files
ig files

# Only Rust files
ig files -t rust

# JSON output for agents
ig files --json

# With glob filter
ig files -g "src/**/*.ts"

# Tree-compressed view — directories with file counts
ig files --compact

# Compact view filtered to PHP files
ig files --compact -t php

Auto-compact on pipe v1.10.0

When stdout is a pipe and the listing has 40+ files, ig files emits a one-line aggregate instead of enumerating every path. A TTY or IG_COMPACT=0 keeps the verbose listing.

$ ig files | head
3201 files in 911 dirs · 972 tsx, 890 php, 790 ts, 80 mdx, 70 py, 47 json
(compact view — set IG_COMPACT=0 or run in a TTY for the full listing)

# iautos monorepo: 176 KB → 149 B (≈1180×)

ig symbols

Extract symbol definitions (functions, classes, structs, interfaces) from source files. Language-aware patterns for Rust, TypeScript, Python, Go, PHP, and more.

ig symbols [OPTIONS] [PATH]

# All symbols in project
ig symbols

# Only Rust symbols
ig symbols -t rust

# JSON output (for agents)
ig symbols --json

# Symbols in specific directory
ig symbols src/

ig context

Show the full code block (function, class, struct) containing a specific line. Automatically detects block boundaries using brace matching or indentation.

ig context <FILE> <LINE>

# Show function containing line 42
ig context src/main.rs 42

# JSON output
ig context --json src/main.rs 42

ig ls

Compact directory listing optimized for AI agents. Groups files by directory, shows file counts, and respects .gitignore and default exclusions. Generates a tree-like overview without the noise.

ig ls [PATH]   # default: current directory

# Compact listing of current project
ig ls

src/          (12 files)
  index/      (6 files)  ngram.rs  reader.rs  writer.rs  ...
  query/      (2 files)  extract.rs  mod.rs
  main.rs  cache.rs  read.rs  smart.rs

# Listing a subdirectory
ig ls src/

ig read

Smart file reading with multiple compression modes. Full mode returns the complete file; --signatures extracts only function/class/struct definitions — dramatically reducing tokens when an AI agent only needs the API surface. Advanced modes offer aggressive compression, token budgets, relevance boosting, and delta views.

ig read <FILE> [OPTIONS]

# Full file content
ig read src/index/reader.rs

# Signatures only (functions + structs — much smaller)
ig read -s src/index/reader.rs

pub fn open_for(root: &Path) -> Result<IndexReader>
pub fn query(&self, ngrams: &NgramQuery) -> Vec<DocId>
pub fn intersect_postings(&self, lists: &[&[u8]]) -> Vec<DocId>

# Aggressive compression — strip comments, collapse blanks, elide bodies
ig read -a src/index/reader.rs

# Budget mode — keep the 500 most informative tokens
ig read -b 500 src/index/reader.rs

# Budget + relevance boost — prioritize payment-related code
ig read -b 500 -r "payment" src/billing.php

# Delta mode — only git-changed lines with enclosing signatures
ig read -d src/main.rs

# Raw output — byte-for-byte identical to cat
ig read -p src/main.rs

ig smart

Generate 2-line heuristic summaries for every file in the project. Each summary captures the file's purpose in minimal tokens — ideal for giving an AI agent a high-level map before deciding which files to read in full.

ig smart [PATH]   # default: current directory

# 2-line summaries for all project files
ig smart

src/index/reader.rs
  mmap-backed index query — hash table lookup + posting intersection.
  Decodes VByte postings on the fly, applies bloom/loc masks.

src/index/ngram.rs
  Sparse n-gram generation via hash_bigram + covering set selection.
  Core algorithm — port of danlark1/sparse_ngrams.

Directory aggregate mode v1.10.0

When the target is a directory and stdout is a pipe, ig smart emits a one-block structural summary instead of reading every file. The per-file mode was O(N files) — hitting 5+ seconds on a 1000-file subtree — and produced a wall of text an agent rarely needs in full. The aggregate is three lines, fast, and usually more useful for orienting in an unfamiliar codebase.

$ ig smart apps/api
apps/api: 1042 files, 249 dirs · 890 php, 39 yaml, 31 twig, 29 sh, 10 md
top: src/ (664), migrations/ (109), tests/ (103), config/ (42)
key: composer.json, README.md, Makefile

# 345 B / 19 ms — down from 69 KB / 5.3 s (≈200× smaller, ≈280× faster)
# Force full per-file summary: IG_COMPACT=0 ig smart apps/api

ig pack

Generate a context.md project map (under the XDG cache dir) — a structured project snapshot for AI agents. Includes directory tree, symbol definitions, dependencies (Cargo.toml / package.json), API routes (Next.js), and environment variables (.env.example). Replaces manual context-building.

ig pack [PATH]   # writes the context.md project map

# context.md contains:

## Directory Tree    — compact ig ls output
## Symbols          — all function/class/struct definitions
## Dependencies     — Cargo.toml or package.json (v1.3+)
## API Routes       — Next.js app/api/** routes (v1.3+)
## Environment      — .env.example keys (v1.3+)

ig gain

Token savings dashboard. Reads the JSONL tracking log written by the rewrite hook and displays cumulative token savings, cost estimates, and per-command breakdowns.

ig gain [OPTIONS]    # show savings dashboard
ig gain --clear      # reset history

v1.10.0: the default dashboard now shows the top 20 commands (was 15). Long-tail ig run <cmd> variants usually fill positions 15-20 and collectively account for a big chunk of savings. Use --full when you need every row.

ig gain

instant-grep token savings
────────────────────────────────
Session:      47 rewrites
Tokens saved: 142,380
Cost saved:   $0.13
Top command:  git status  (38 rewrites, 91K tokens)

# Main dashboard
ig gain

# Daily savings chart (last 14 days)
ig gain --graph

# Monthly token projection
ig gain --quota

# Current project only
ig gain -p

# Find missed optimization opportunities
ig gain --discover

# Per-command history with individual savings (new in v1.4)
ig gain --history

# Machine-readable JSON output (new in v1.4)
ig gain --json

command history (last 10)
────────────────────────────────────────────
2026-03-27 14:32  git status    -605B   (-83%)
2026-03-27 14:35  git log -10   -7,864B (-89%)
2026-03-27 14:41  grep -r …     -2,100B (-94%)
2026-03-27 14:50  git diff      -19,382B (-74%)

ig setup alias: ig init

Auto-configure AI CLI agents to use ig. Detects installed agents and injects configuration — hook scripts, settings.json patches, and managed rule-file blocks. Idempotent and non-destructive — safe to run multiple times. ig init is an accepted alias for RTK muscle memory.

ig setup supports 11 agents: claude, codex, cursor, copilot, gemini, opencode, windsurf, cline, hermes, kilocode, antigravity.

Claude Code's PreToolUse hook uses the RTK 0/1/2/3 exit-code protocol: 0 = rewrite/allow, 1 = passthrough, 2 = deny, 3 = ask. Run ig hook-audit to audit installed hooks and the recent permission-verdict histogram.

# Configure every detected agent
ig setup

# One agent only
ig setup --agent claude

# Preview without writing
ig setup --dry-run

# Show what is installed
ig setup --show

# Configure + import RTK filters in one shot
ig setup --import-rtk

ig import-rtk v2.0.0

One-shot translation of RTK filter files into ig's filter format. Reads ~/.config/rtk/filters.toml and ./.rtk/filters.toml and writes the equivalent ig filters. RTK fields (match, strip_ansi, keep, drop, truncate, head, tail, max_lines, on_empty, dedup_consecutive) map 1:1; RTK-only features that ig already covers with a native parser are skipped with a comment.

ig import-rtk             # translate RTK filter files
ig import-rtk --dry-run   # preview the translation without writing

ig git

Token-compressed git proxy. Strips verbose output, filters noise, and tracks token savings. Supports status, log, diff, show, and branch. Transparent — the output is still valid git output, just compressed.

ig git <SUBCOMMAND> [GIT OPTIONS]

# Compressed git status (127B instead of 732B)
ig git status

# Compact log — 10 entries, -89% token reduction
ig git log -10

# Diff with noise stripped
ig git diff

# Show last commit
ig git show HEAD

# Branch list
ig git branch

ig discover

Scan agent session history (and optionally shell history) for missed token-saving opportunities — commands that could have gone through ig run but didn't. Helps you tune your hook coverage.

ig discover [OPTIONS]   # scan agent + shell history

# Scan the last 30 days of sessions
ig discover

# Scan everything, including shell history
ig discover --all --shell

# Cap to top 20 entries per section
ig discover --limit 20

ig run alias: ig proxy

Run any command through ig's token-optimized filter pipeline. The output is compacted by a TOML-driven filter (8 stages: ansi, replace, keep, drop, truncate, head, tail, fallback) and the wrapped command's exit code is propagated. When the output can't be parsed, ig falls back to raw passthrough. ig run also transparently routes ls, find, cat, and git status/log/diff to the dedicated ig subcommands (opt out with IG_RUN_ROUTE=0).

ig run <COMMAND> [ARGS...]    # run through the filter pipeline
ig proxy <COMMAND> [ARGS...]  # alias

# Run a build command with filtered output
ig run cargo build

# Routes to the dedicated subcommand automatically
ig run git status     # → ig git status
ig run ls src/        # → ig ls src/

# See the filter / rewrite decision without changing behaviour
ig --explain run cargo test

Command wrappers v2.0.0

v2.0.0 ships native Rust wrappers for 33 common developer tools — feature parity with rtk. Each wrapper parses the tool's output (JSON where available), emits a compact summary, propagates the wrapped tool's exit code, honours -u/--ultra-compact, and falls back to raw passthrough when the output can't be parsed.

# Test runners — compact pass/fail summary
ig vitest
ig pytest tests/
ig cargo-test

# Linters — only files with diagnostics
ig eslint src/
ig tsc --noEmit
ig ruff check .

# Git platforms / cloud
ig gh pr list
ig kubectl get pods
ig aws s3 ls

# Ultra-compact, minimum signal
ig -u jest

Meta commands

ig setup / ig init (agent configuration), ig import-rtk (RTK filter migration), ig hook-audit (audit installed hooks + recent permission verdicts), and ig telemetry (opt-in anonymous telemetry — off by default; the public build compiles in no endpoint, so it is a hard no-op).

JSON output format (--json)

Structured, parseable, minimal tokens. Supported by search, files, symbols, and context.

{
  "pattern": "async fn",
  "matches": [
    {
      "file": "src/index/reader.rs",
      "line": 23,
      "text": "pub fn open_for(root: &Path) -> Result<IndexReader> {"
    }
  ],
  "stats": {
    "duration_ms": 0.9,
    "candidates": 47,
    "matches": 3
  }
}