scip-cli
Python CLI for AI agents. Queries SCIP indexes for precise refs, definitions, and repo health analysis — TypeScript/JavaScript, Python, Go, Rust.
Related (optional): scip-atlas builds atlas.db (git paths, commits, owners) from this cache's index.db. scip-atlas-web packs both into a slim DB and a single-file browser explorer. You do not need them for CLI or agent workflows.
Why
AI agents waste tokens on grep and file scanning. scip-cli gives them precise, type-aware code navigation in milliseconds — and analyze surfaces dead code, cycles, and coupling so agents (and humans) can fix real problems fast.
Features
- Agent-first: Install as a skill for Claude Code, Cursor, or any AI agent — precise code navigation without burning context
- Token-efficient: One record per line, stderr for warnings, pipe-friendly output
- Fast: Direct SQLite queries — 10x to 213x faster than alternatives
analyze: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope- Auto-indexing: Indexes on first query, caches in SQLite, zero config
Ports
CLI/output parity ports of this project (Python is the reference):
| Language | Repository |
|---|---|
| Python (reference) | flesler/scip-cli |
| Go | flesler/scip-cli-go |
| Rust | flesler/scip-cli-rust |
| Zig | flesler/scip-cli-zig |
For AI Agents
Install as a reusable skill so your agent always knows how to navigate the codebase:
scip-cli skill ~/.claude/skills/scip-cli/ # Claude Code
scip-cli skill ~/.cursor/skills/scip-cli/ # Cursor
Or dump the quick reference for one-off use:
scip-cli skill
Installation
1. Install scip-cli
From PyPI (end users):
pip install scip-cli
Local development — almost always keep bare scip-cli mapped to this checkout via editable install. You edit the repo; the CLI you run is live code, not a frozen PyPI copy.
cd scip-cli
pip install -e ".[dev]"
scip-cli --version
All docs and examples use scip-cli (never .venv/bin/scip-cli or python -m scip_cli). After publishing, briefly pip install scip-cli to smoke-test PyPI, then pip install -e ".[dev]" again.
Optional venv for isolation — activate it, run the same editable install, still invoke scip-cli on PATH:
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
Tests and lint: scripts/test.sh (same as CI and pre-commit), or run pytest, ruff check ., basedpyright --warnings scip_cli/ scripts/ from .venv.
2. Install prerequisites (optional)
On first index, scip-cli runs language indexers and builds a SQLite cache. You can let it fetch tools on demand, or install them globally ahead of time so the first run does not download via npx:
Option A: Zero extra setup (recommended)
Install scip-cli and run it. On first index, scip-cli will:
- Install
scip-typescriptfrom the flesler/scip-typescript fork (feat/partial-files) when not on PATH — clones,npm install, and builds into~/.cache/scip-cli/tools/github-npm/(upstream npm does not ship partial--filesyet) - Download
scip-pythonvianpx,scip-goviago install, orrust-analyzerviarustupwhen not already on PATH - Download the
scipconverter binary from GitHub releases into~/.cache/scip-cli/bin/when not already on PATH - Walk the repo for
tsconfig*.jsonproject roots (TypeScript monorepos), runscip-typescriptper project (parallel by default), convert each partial index, then merge into oneindex.db
No .scip-cli.json required for discovery. Subsequent queries read the cached database only.
Option B: Install indexers globally ahead of time
Same indexing steps as Option A; this only avoids the first-run download/build:
# TypeScript/JavaScript indexer — fork with partial --files (required for incremental reindex)
git clone --depth 1 --branch feat/partial-files https://github.com/flesler/scip-typescript.git
cd scip-typescript && npm install --ignore-scripts && npm run build && npm install -g .
# Python indexer
npm install -g @sourcegraph/scip-python
# Go indexer
go install github.com/scip-code/scip-go/cmd/scip-go@latest
# Rust indexer (rust-analyzer with SCIP support)
rustup component add rust-analyzer
# SCIP CLI for index conversion (GitHub release — not on npm)
# https://github.com/scip-code/scip/releases (v0.8.1+ recommended)
Verify installation:
scip-cli --help
scip-typescript --version # Only if you chose Option B
scip --version # Install from GitHub releases; v0.8.1+ recommended
Usage
All commands are subcommands of scip-cli:
scip-cli <command> [arguments]
Commands
refs <symbol>- Find all references to a symbol (--pathto scope)code <symbol>- Find symbol definition with source code (--path,--max-lines,--full,--offset,--snippet,--line-numbers)search <pattern>- Search symbols by name pattern (--path)symbols <file>- List all symbols in a file (--path; bare filename OK)rdeps <file>- Find files that depend on a file (--path)deps <symbol|file>- Find outbound dependencies (what a symbol or file calls) (--path,--paths-only)members <symbol>- List members of a class/interface (--path)query <sql>- SQL against the project index (--format tsv|csv|json, default tsv; read-only unless--write)analyze [target]- SQL health dashboards (--limit,--per-check-limit,--priority,--check,--include-tests). No target: project-wide; directory or file path; symbol name. See Finding easy wins withanalyze.reindex- Force re-indexing (--path,--tsconfig,--exclude,--fresh,--no-incremental; incremental by default in git TS repos)skill [path]- Install or dump the SKILL.md
Examples
# Find where greet is used
scip-cli refs greet
# Get definition of greet
scip-cli code greet
# Search for symbols matching "Widget"
scip-cli search Widget
# Scope to a subdirectory
scip-cli code greet --path packages/api
# List symbols by bare filename
scip-cli symbols helper.ts
# Find files that import from a module
scip-cli rdeps src/helper.ts
# Find what a function calls
scip-cli deps greet
# Find what a file depends on
scip-cli deps src/helper.ts --paths-only
# List members of a class
scip-cli members Widget
# Project health dashboard (or: scip-cli analyze src/foo.ts / scip-cli analyze greet)
scip-cli analyze
# List index tables / columns (read-only SQL)
scip-cli query "SELECT name FROM sqlite_schema WHERE type='table' ORDER BY 1"
scip-cli query "PRAGMA table_info(global_symbols)"
# Install skill file
scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
Pipelines
Stdout is one record per line; stderr carries warnings and ambiguity notices. Kinds are lowercase (function, class, method, property). Pipe-friendly flags: refs --paths-only, search --names-only / --paths-only, members --names-only, deps --paths-only. rdeps already prints bare file paths.
# What do importers of this file export?
scip-cli rdeps src/helper.ts | xargs -I{} scip-cli symbols {}
# Which files reference a symbol?
scip-cli refs greet --paths-only
# Classes matching a name → list their members
scip-cli search Handler --kind class --names-only | xargs -I{} scip-cli members {}
# Walk class members to their definitions
scip-cli members Widget --names-only | xargs -I{} scip-cli code Widget.{}
# Find all files that a symbol depends on (outbound dependencies)
scip-cli deps greet --paths-only | sort -u
How It Works
- On first query, automatically detects project language from
package.json(TS/JS),pyproject.toml/setup.py(Python),go.mod(Go), orCargo.toml(Rust) - For TypeScript monorepos, walks the repository for
tsconfig*.jsonproject roots (nested ancestors deduped; root included only when itsincludeis broad) - Runs
scip-typescriptper project (in parallel when there are multiple projects; setSCIP_CLI_INDEX_WORKERS=1to force serial),scip-pythonfor Python,scip-gofor Go, orrust-analyzer scipfor Rust - Converts each SCIP output to SQLite with
scip expt-convert, then merges partial databases when needed - Caches the result in
~/.cache/scip-cli/projects/<dirname>-<hash>/index.db(e.g.my-monorepo-1a3f7a) - Compacts the database after each reindex (
VACUUM+ WAL checkpoint) - Subsequent queries are SQLite lookups against that cache (not re-indexing)
Incremental reindex (TypeScript, v3.0+): plain scip-cli reindex in a git worktree is incremental by default — reuses unchanged tsconfig shards via shards/manifest.json (git_commit + per-shard tsconfig_digest). Dirty shards reindex only changed files (git delta → importer closure → fork --files) and upsert into the live index.db. Use --no-incremental or --fresh for a full rebuild; --unversioned and non-git projects always full-reindex. Bench locally with python scripts/bench_incremental_gate.py --branch fixture.
Configuration
Optional .scip-cli.json in the project root:
{
"maxHeapMb": 8192,
"indexRoots": ["packages/core", "apps/worker"],
"onlyIndexRoots": false
}
maxHeapMb— Node heap forscip-typescript/scip-python(default 8192 MB when omitted). Overridden bySCIP_CLI_MAX_HEAP_MB. This is the V8 heap cap, not total RAM usage. Does not affectscip-go.indexRoots— extra TypeScript project directories to include on first index, merged with auto-discovered projects.onlyIndexRoots— skip auto-discovery and index onlyindexRoots(smaller initial index when you only care about part of a monorepo).
SCIP_CLI_INDEX_WORKERS controls parallel indexer runs during first index (default: up to 8). Merge into one database is always serial.
Other environment variables:
| Variable | Purpose |
|---|---|
SCIP_CLI_MAX_HEAP_MB |
Node heap for scip-typescript / scip-python (overrides maxHeapMb in config) |
SCIP_CLI_TS_INDEX_BATCH_SIZE |
Split large TS repos into multiple scip-typescript runs (default: all tsconfigs in one run) |
SCIP_CLI_MERGE_BATCH_SIZE |
SQLite ATTACH batch size when merging part DBs (max 9) |
SCIP_CLI_INDEX_TIMING |
1 — per-phase INDEX_TIMING: lines on stderr during reindex |
SCIP_CLI_MAX_DEF_LINES |
Max definition lines in code output |
SCIP_CLI_DEBUG |
Log SQL queries to stderr |
Version policy: only the scip converter (expt-convert) is pinned to the 0.8.x release line because it defines the SQLite schema. TypeScript uses flesler/scip-typescript feat/partial-files (see SCIP_TYPESCRIPT_NPX_PACKAGE in scip_cli/indexing/constants.py) — auto-built when not on PATH; switch back to @sourcegraph/scip-typescript on npm once upstream merges --files. scip-python via npx at latest; scip-go via go install @latest. rust-analyzer installs via rustup component add.
Large monorepos (>10 tsconfig projects) log per-project progress to stderr during indexing; smaller repos stay quiet aside from the final Indexed … (size) line.
Scoped indexing without editing .scip-cli.json:
scip-cli reindex --path packages/core
scip-cli reindex --path packages/api --path packages/worker
scip-cli reindex --tsconfig 'apps/api/tsconfig.*.json'
scip-cli reindex --tsconfig tsconfig.app.json --tsconfig tsconfig.spec.json
scip-cli reindex --exclude '**/*.test.ts' '**/*.spec.ts'
scip-cli reindex --exclude # clear persisted excludes
scip-cli reindex --fresh # full index; clear metadata.json
scip-cli reindex --no-incremental # full rebuild; clears shard manifest
--path limits which discovered tsconfig directories are indexed (prefix match, same idea as query --path). --tsconfig skips discovery and indexes those tsconfig*.json files (repeatable; globs are repo-relative to the detected project root — run from monorepo root or shorten the glob). File-based runs default to one scip-typescript process per file so each gets its own heap (SCIP_CLI_TS_INDEX_BATCH_SIZE still overrides). Cannot combine --path and --tsconfig. TypeScript only for --path and --tsconfig. Scope and exclude defaults are saved in metadata.json next to index.db and reused on later reindex runs; use reindex --fresh to clear them and restore a full index. --exclude updates the persisted exclude list (honored during incremental reindex too); a lone bare --exclude clears it. Incremental is the default in git TypeScript repos; --no-incremental, --fresh, --unversioned, or non-git force full reindex.
When a tsconfig (after extends) has allowJs: true, matching .js/.jsx files under that config's include/files are indexed too (same roots as .ts/.tsx). allowJs: false or unset leaves JavaScript out. JS-only repos with no tsconfig.json still use --infer-tsconfig.
Run scip-cli reindex after changing scope, .scip-cli.json index settings, or when you want a fresh index.
Finding easy wins with analyze
Use analyze on the repo itself before broad refactors or agent review — it surfaces cross-file issues from the SCIP index (not Python vulture).
Quick pass (after scip-cli reindex):
scip-cli analyze --list-checks # all --check NAME values (no index)
scip-cli analyze --limit 25
scip-cli analyze --limit 40 --per-check-limit 5 # spread the global budget across checks
scip-cli analyze --priority high --limit 25 # dead exports & cycles only
scip-cli analyze --check cycles --limit 25 # one named section
scip-cli analyze --check dead_files --limit 25
scip-cli analyze --check dead_exports,dead_files,single_importer_files,one_line_exports --priority high,low --limit 40
--limit is a global finding-row budget (truncation markers do not count). --per-check-limit (default unlimited) caps each section. Directory analyze spends that same budget on per-file dumps after dashboards.
Sections are tagged [high], [medium], [low] and listed in that order.
| Tier | Project sections | Action |
|---|---|---|
| high | Cycles, dead exports, dead files, stale types (unreferenced is omitted when dead exports is on) | Nuke or fix cycles; delete unused; _ prefix |
| medium | Same-file only, change surface (file target) | Module-private by usage |
| low | Single-importer files ([test-only] when sole importer is tests), test-only consumers, coupling, bottlenecks, hotspots, one_line_exports (exported call-through shims) |
Noisy on Python (index omits many same-file calls); verify with rg. one_line_exports uses SCIP def line span (Prettier-wrapped signatures count as extra LOC). |
Use --priority high for a quick gate; --priority high,medium adds context. File drill-down adds change surface, unused_imports, and single_use_imports (not the same as project single_importer_files). Run scip-cli analyze --list-checks for the full checklist.
What to look at first
| Section | Easy pickings |
|---|---|
| Cycles | Import/mention cycles between production files — break the edge or extract shared code |
| Unreferenced | Same survivors as dead exports; omitted unless --check unreferenced. Empty rdeps is usually a SCIP miss — verify with rg -F STEM (file basename in (...)) |
| Dead exports | No external refs — delete or _ prefix |
| Stale types | Classes/types with no external consumer in the index — verify in-file or type-only use before removing |
| Same-file only | Used only inside defining file — rename to _ |
| Test-only consumers | Cross-file refs are all from tests — promote to e2e or accept as internal |
Per-file or package drill-down on hubs or suspects:
scip-cli analyze scip_cli/queries.py --limit 20 # file: scoped project + per-file + top symbols
scip-cli analyze scip_cli --limit 15 # directory: scoped project + each file under it
Dead exports in file lists same-module symbols with no external refs — module-private _helpers are filtered out. Remaining rows are worth a manual rg check.
Defaults: project-wide and directory analyze skip tests/, *.test.*, *.spec.*, conftest.py, and __tests__/. Pass --include-tests to include them. File-target analyze always includes that file.
Limits: "Dead export" means no cross-file mentions in the index — not unreachable code. Same-file private helpers are expected. Shebang lines and manifest entrypoints (package.json main/bin/scripts with dist→src mapping for TypeScript; Python pyproject/setup.py/setup.cfg scripts) are excluded from project-level dead files and dead exports. Re-run reindex after large changes; the index is a snapshot.
Performance
Inspired by scip-query, scip-cli is a lightweight Python partial reimplementation optimized for speed. Compared to the original:
refs: 6.4s → 0.03s (213x faster)code: 2.8s → 0.05s (56x faster)search: 2.6s → 0.03s (87x faster)symbols: 0.3s → 0.02s (15x faster)rdeps: 0.2s → 0.02s (10x faster)members: 3.1s → 0.03s (103x faster)
The speedup comes from using optimized direct SQLite queries and cutting some nice but very slow goodies (like ts-morph).
Development
pip install -e ".[dev]"
pytest tests/ -q
pytest tests/ -m integration -q # indexes tests/fixtures/typescript-project (needs scip-typescript)
Debug Logging
Set SCIP_CLI_DEBUG=1 to enable SQL query logging to stderr (statements truncated to 200 chars):
SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
# Shows: SQL: SELECT ... | params: (...)
This is useful for testing and debugging SQL queries
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines. By participating, you agree to the Code of Conduct.
Security
To report a security vulnerability, see SECURITY.md.
License
MIT
Metadata
Release files for scip-cli 3.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scip_cli-3.4.0.tar.gz | 176.6 kB | Without provenance | Details for scip_cli-3.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scip_cli-3.4.0-py3-none-any.whl | Python 3 | none | any | Details for scip_cli-3.4.0-py3-none-any.whl |
Total release size: 303.3 kB
Release files / scip_cli-3.4.0.tar.gz
| Download URL | scip_cli-3.4.0.tar.gz |
|---|---|
| Size | 176.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3bb52142b0adead09d78e0b040833fcb997d7d4df7726029b0f787ea0a468017
|
|
BLAKE2b-256 checksum How to use checksums |
806fcc10175f9d4d5e4d143b70598d8267693d008fa972f3741c12ffbccb8189
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Release files / scip_cli-3.4.0-py3-none-any.whl
| Download URL | scip_cli-3.4.0-py3-none-any.whl |
|---|---|
| Size | 126.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98a73bdda5bde256af3b0bb69543ee0883aa2c29ea0188dd86cbe28f825d9701
|
|
BLAKE2b-256 checksum How to use checksums |
5e62385ac0a2db3962b18f2e86a7af63807ed0ee7d17736db6b84c6324f20c7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Security for scip-cli 3.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.