Skip to content

cli.md

Latest commit

 

History

History
222 lines (162 loc) · 8.89 KB

cli.md

File metadata and controls

222 lines (162 loc) · 8.89 KB
Raw

CLI Guide

The CLI is the easiest way to test the engine locally.

Use a file-backed SQLite path for --db. :memory: is only supported by direct storage-layer tests, not by the public CLI/MCP tool flow.

Index a Repository

cargo run -p context-cli -- index --repo crates/context-indexer/tests/fixtures/simple_rust --db .context/example.sqlite

Expected shape:

{
  "files_indexed": 1,
  "files_updated": 1,
  "files_removed": 0,
  "chunks_indexed": 3,
  "symbols_indexed": 3,
  "edges_indexed": 5,
  "provider_diagnostics": []
}

Indexing is incremental by default. Unchanged files are skipped, changed files are re-chunked, files removed from the repository are removed from the SQLite index, and the Tantivy sidecar is rebuilt from the committed SQLite state.

Use --force to rebuild the selected repository only:

cargo run -p context-cli -- index --repo crates/context-indexer/tests/fixtures/simple_rust --db .context/example.sqlite --force

Add one or more external reference-provider configs to ingest compiler/type-checker-backed edges during indexing:

cargo run -p context-cli -- index --repo . --db .context/example.sqlite --reference-provider-config .context/scip-rust-provider.json

Provider config files are JSON:

{
  "name": "scip-rust",
  "command": "scip-rust-provider",
  "args": ["--workspace", "."],
  "languages": ["rust"],
  "compiler_grade": true,
  "strict": true,
  "timeout_ms": 30000
}

The provider command receives repo/chunk/symbol metadata on stdin and writes graph edges on stdout. Use separate configs for rust-analyzer/SCIP, TypeScript, and Python type-checker providers.

The CLI includes first-party provider adapters that speak this protocol. They still require the underlying tools to be installed:

cargo run -p context-cli -- provider rust-analyzer-scip
cargo run -p context-cli -- provider java-scip
cargo run -p context-cli -- provider typescript
cargo run -p context-cli -- provider python

Portable provider path resolution uses the following precedence:

Tool or path CLI option Environment variable Automatic fallback
Rust Analyzer --rust-analyzer CONTEXT_RUST_ANALYZER rust-analyzer on PATH
Rust SCIP output --scip-output CONTEXT_SCIP_OUTPUT CONTEXT_TMP_DIR, then the operating system temporary directory
Node.js --node CONTEXT_NODE node on PATH
TypeScript CLI --tsc CONTEXT_TSC repository node_modules/.bin/tsc, then tsc on PATH
TypeScript API --typescript-api CONTEXT_TYPESCRIPT_API repository node_modules/typescript/lib/typescript.js
Pyright CLI --pyright CONTEXT_PYRIGHT repository node_modules/.bin/pyright, then pyright on PATH
Python --python CONTEXT_PYTHON Pyright interpreter selection
Pyright LSP --pyright-langserver CONTEXT_PYRIGHT_LANGSERVER repository node_modules/pyright/langserver.index.js
Generated scripts n/a CONTEXT_TMP_DIR operating system temporary directory

Example config for the Rust adapter:

{
  "name": "scip-rust",
  "command": "context",
  "args": [
    "provider",
    "rust-analyzer-scip",
    "--timeout-ms",
    "120000"
  ],
  "languages": ["rust"],
  "compiler_grade": true,
  "strict": true,
  "timeout_ms": 120000
}

Example config for the Java SCIP adapter:

{
  "name": "scip-java",
  "command": "context",
  "args": [
    "provider",
    "java-scip",
    "--timeout-ms",
    "120000"
  ],
  "languages": ["java"],
  "compiler_grade": true,
  "strict": true,
  "timeout_ms": 120000
}

The TypeScript adapter runs tsc --noEmit --strict, then uses the stable TypeScript compiler/language-service API (typescript/lib/typescript.js) for symbol references and call edges. It discovers repository-local TypeScript packages by walking from the indexed repository toward its ancestors, and extensionless Node scripts such as bin/tsc are launched through --node. The Python adapter runs Pyright diagnostics and then uses pyright-langserver LSP references, with --lsp-startup-delay-ms controlling the wait after didOpen. The Rust adapter runs rust-analyzer scip and maps SCIP occurrences back to indexed symbol IDs. The Java adapter runs scip-java index, then maps the generated index.scip occurrences back to indexed Java symbol IDs. Adapter --timeout-ms limits direct provider subprocess execution; external provider configs can also set timeout_ms. On Windows, timed-out adapter and external-provider commands are attached to an unnamed Job Object when available so child processes are terminated with the provider. UTF-8 provider config files with or without BOM are accepted, and provider diagnostics are returned in provider_diagnostics.

Search Metadata

cargo run -p context-cli -- search --db .context/example.sqlite --query run --limit 5

Search returns metadata only. It does not return full source text.

Add --vector to fuse the deterministic local hash-vector signal into search results:

cargo run -p context-cli -- search --db .context/example.sqlite --query scheduler --limit 5 --vector

Use vector-search for vector-only retrieval:

cargo run -p context-cli -- vector-search --db .context/example.sqlite --query "schedule cadence" --limit 5

The vector signal is local feature hashing over indexed metadata and source text. It does not download a model.

Fetch Exact Source

cargo run -p context-cli -- get-chunk --db .context/example.sqlite --chunk-id "<chunk_id from search>"

get-chunk is the explicit source retrieval step.

Find References

cargo run -p context-cli -- find-references --db .context/example.sqlite --symbol run

Reference edges include provider, confidence, and evidence. The built-in provider is heuristic, so treat it as investigation guidance rather than a compiler-grade call graph. Syntactic calls are stored as calls graph edges for context expansion and impact hints, but find-references still returns reference/test-reference edges only.

Expand Context

cargo run -p context-cli -- expand-context --db .context/example.sqlite --chunk-id "<chunk_id from search>" --depth 1 --limit 10 --token-budget 4000

The response contains metadata-only expanded chunks, graph symbols, graph edges, total_estimated_tokens, token_budget, and budget_exhausted.

Pre-Change Context

cargo run -p context-cli -- pre-change-context --db .context/example.sqlite --task "change run behavior" --limit 10 --depth 1 --token-budget 4000

Add --repo <path> to scope search/expansion to that repository and include matching project memories in the returned context pack:

cargo run -p context-cli -- pre-change-context --db .context/example.sqlite --repo . --task "change run behavior" --limit 10 --depth 1 --token-budget 4000

The response contains search results, suggested chunk IDs, a budgeted metadata context pack, and any matching memories. Fetch full source only for selected chunks with get-chunk.

Project Memory

Memories are durable, repo-scoped notes anchored to a repo, file, symbol, or span. They stay local in SQLite and are reconciled against the current index.

cargo run -p context-cli -- memory-add --db .context/example.sqlite --repo . --anchor-kind symbol --anchor-id run --anchor-path src/lib.rs --text "run preserves the existing public behavior"
cargo run -p context-cli -- memory-list --db .context/example.sqlite --repo .
cargo run -p context-cli -- memory-reconcile --db .context/example.sqlite --repo .
cargo run -p context-cli -- memory-delete --db .context/example.sqlite --memory-id "<memory_id>"

Statuses are current, relocated, stale, or gone. Use memory-list --status current to filter.

Analyze Impact

Manual inputs:

cargo run -p context-cli -- impact --db .context/example.sqlite --changed-files src/lib.rs --changed-symbols run --depth 1

Post-change diff input:

cargo run -p context-cli -- post-change-impact --db .context/example.sqlite --diff-file .context/change.diff --depth 1

post-change-impact also accepts --changed-files, --changed-symbols, and inline --diff. Use either --diff or --diff-file, not both.

Impact output combines the available graph edges and includes provider labels in impact reasons. With only the built-in provider it is heuristic and should be used to choose what to inspect or test next; configured compiler/type-checker providers add higher-confidence evidence without making the whole report a formally sound call graph.

Start MCP Stdio

cargo run -p context-cli -- mcp-stdio

Smoke test:

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | cargo run -p context-cli -- mcp-stdio
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | cargo run -p context-cli -- mcp-stdio