IoContext CLI

iocontext-cli is an npm package that installs two commands:

• iocontext (CLI wrapper)
• iocontext-mcp (MCP stdio server)

Current scope of this repo:

• CLI exposes subcommands: code-search, ingest, ignore, mcp
• MCP exposes one tool: code_search

Requirements

• Node.js 18+ and npm
• ripgrep available in PATH (rg)

Rust/Cargo is only needed for local development builds of the binaries.

Install

npm install -g iocontext-cli@latest

On install, postinstall downloads prebuilt native binaries into dist/bin.

When available in release assets, npm postinstall also downloads bundled rg (ripgrep) into dist/bin. Wrappers (iocontext, iocontext-mcp) automatically set IOCONTEXT_RG_BIN to that bundled path.

Verify

iocontext --help
iocontext-mcp --help

CLI Usage

The iocontext command is a wrapper around the native iocontext binary.

Available command:

iocontext code-search --request <request.json>

Global option:

iocontext -C <repo-path> code-search --request <request.json>

If request.json has an empty repo field, the value from -C is used.

Request JSON example

Create request.json:

{
	"repo": "D:/work/my-repo",
	"glob": "**/*.py",
	"literal": false,
	"max_matches": 100,
	"probes": [
		"def authenticate",
		{
			"pattern": "class UserService",
			"path": "src"
		},
		[
			"TODO:|FIXME:",
			"--glob",
			"*.py"
		]
	]
}

Run:

iocontext code-search --request request.json

MCP Usage

Start stdio MCP server:

iocontext-mcp

Exposed tool:

• code_search

Important behavior:

• repo is required in tool arguments
• default search mode is regex (literal defaults to false)
• set literal: true for fixed-string matching
• output is grouped text only

Development (from source)

Build binaries:

cargo build --release --bin iocontext --bin iocontext-mcp

Ingest CLI (SQLite local graph)

iocontext ingest indexes JS/TS/Python source into a local SQLite graph database.

Current graph relations in ingest v1:

• CONTAINS (Folder->Folder, Folder->File, File->Symbol)
• IMPORTS (File->File)
• CALLS (Function/Method/File -> target symbol)
• HAS_METHOD (Class->Method)
• EXTENDS (Class->Class)
• IMPLEMENTS (TypeScript Class->Interface)
• METHOD_OVERRIDES (Method->Method)

Default database path:

• <repo>/.iocontext/graph.sqlite

Graph JSON export:

• Every ingest run also writes a JSON snapshot for web/remote upload workflows.
• Default path: <repo>/.iocontext/graph.json
• If --db is set, JSON is written next to that DB path as graph.json.

Examples:

# Incremental (changed files only)
cargo run --bin iocontext -- ingest --repo D:/work/my-repo --mode changed-only

# Full rebuild
cargo run --bin iocontext -- ingest --repo D:/work/my-repo --mode full

# Custom DB path + verbose output
cargo run --bin iocontext -- ingest --repo D:/work/my-repo --db D:/tmp/my-graph.sqlite --verbose

# Include/exclude globs
cargo run --bin iocontext -- ingest --repo D:/work/my-repo --include "src/**/*.ts" --exclude "**/*.test.ts"

Main flags:

• --repo <path> repo root (default .)
• --db <path> custom sqlite output path
• --mode <full|changed-only> ingest mode
• --include <glob> include patterns (repeatable)
• --exclude <glob> exclude patterns (repeatable)
• --hidden include hidden files during scan
• --max-workers <n> reserved for upcoming parallel phase
• --verbose print phase summaries

Ignore CLI (.ioignore)

iocontext ignore add manages .ioignore at repo root.

.ioignore is used by:

• graph ingest scanner (iocontext ingest)
• code_search exclusions (iocontext code-search / MCP code_search)

Examples:

# Add a folder (normalized to recursive pattern)
cargo run --bin iocontext -- -C D:/work/my-repo ignore add src/generated

# Add file and glob entries
cargo run --bin iocontext -- -C D:/work/my-repo ignore add src/tmp.py "**/*.snap"

Notes:

• Duplicate entries are deduplicated.
• Paths outside the repo are rejected.
• Directory entries are normalized to <dir>/**.

Global ignore behavior:

• Global ignore file lives at <HOME>/.iocontext/.ioignore.
• If global ignore does not exist yet, IoContext creates it with default ignore patterns.
• Effective ignore set for code_search and ingest scanner is: global .iocontext/.ioignore + repo .ioignore + CLI --exclude / exclude_glob.

MCP Setup CLI

Use iocontext mcp setup to generate starter MCP config templates for:

• Claude
• Cursor
• Copilot
• Antigravity

Command also writes a generic JSON sample for unknown agents and prints that sample to stdout.

Example:

cargo run --bin iocontext -- mcp setup

Generated files are placed under:

• <HOME>/.iocontext/mcp/

Usage HTML CLI

Use iocontext usage --html to generate a readable HTML dashboard from .iocontext/usage.json.

Examples:

# Write default HTML output
cargo run --bin iocontext -- -C D:/work/my-repo usage --html

# Write to custom output file
cargo run --bin iocontext -- -C D:/work/my-repo usage --html --out D:/tmp/usage-report.html

Behavior:

• Reads <repo>/.iocontext/usage.json.
• Writes HTML to <repo>/.iocontext/usage.html by default.
• Shows a warning banner when saved_tokens is negative (token deficit / token loss).

Backend compatibility:

• Current default backend is SQLite local file (.iocontext/graph.sqlite).
• Ingest pipeline uses a store abstraction so a future Ladybug backend can be added without changing CLI shape.

Wrapper scripts will also use local binaries if found in:

• target/debug (preferred for local development)
• target/release
• dist/bin (fallback)

Troubleshooting

If CLI prints binary not found:

• reinstall package to trigger postinstall download
• or build from source with cargo and keep binaries in target/release

If npm install cannot download release assets:

• set custom base URL with IOCONTEXT_DOWNLOAD_BASE
• reinstall

Example:

set IOCONTEXT_DOWNLOAD_BASE=https://github.example.com/my-mirror/releases/download
npm install -g iocontext-cli@latest

If ingest hits Windows file-lock contention:

• retry the command (SQLite busy timeout/retry is enabled)
• close other tools that keep a handle on graph.sqlite (DB viewers, long-running scripts)
• rerun with --mode full if previous run was interrupted mid-operation

If ingest is slow on large repos:

• narrow scope with --include and --exclude globs
• start with focused paths (for example src/**/*.ts) before broad runs
• use --mode changed-only for repeated local iteration

If code-search returns spawn rg failed: rg.exe: program not found:

• install ripgrep and ensure rg is available in PATH
• then rerun iocontext code-search (or MCP code_search)

If mcp setup is used, it also prints rg status: ... so users can quickly verify whether search runtime is ready.

Uninstall

npm uninstall -g iocontext-cli

License

MIT (see Cargo.toml).