CLI API

Every flag, in one searchable table

nci is the source of truth — nci-mcp and the Node shim both call it. The reference below mirrors nci --help and is grouped by subcommand.

Top-level shape

nci

Usage: nci [OPTIONS] <COMMAND>

Commands:
init           Interactive setup (or -y): create nci.config.json and open the database
db             Database maintenance and lifecycle commands
index          Scan node_modules and update the index
query          Search and inspect indexed package data
sql            Run SQL that only reads the index (no writes)
completions    Print shell completions
binary-path    Print the absolute path of the running nci executable [aliases: which]
upgrade        Upgrade to a newer release and run db migrate
help           Print this message or the help of the given subcommand(s)

Options:
    --database <PATH>     Path to nci.sqlite (overrides nci.config.json)
    --format   <FORMAT>   Output format for supported commands [possible values: plain, json, jsonl]
-h, --help                Print help
-V, --version             Print version

Subcommand tree

nci

Commands:
init            Open the database and run migrations (non-interactive)
migrate         Apply pending SQLite schema migrations
backfill        Run deferred per-package symbol backfill (when pending)
status          Database path/size and health checks (optional)
clear           Delete all indexed package rows (prompts unless -y)
remove          Remove one package from the index (prompts unless -y)
remove-glob     Remove packages whose name matches a SQLite GLOB
destroy         Delete the SQLite file on disk (requires --force)
vacuum          Run VACUUM
wal-checkpoint  PRAGMA wal_checkpoint(TRUNCATE)

nci

Commands:
find              Full-text search symbols by query text
symbol            Exact symbol-name search with package/source filters
show              Show one symbol by stable symbol id
snippet           Print cite-ready signature snippet for a stable symbol id
overloads         List overload siblings for a stable symbol id
packages          List packages currently indexed in the database
package-versions  List indexed versions for a package name
package-deps      List declared package dependencies for a package name/version
source-packages   List distinct source packages for one indexed package version
active-package    Resolve active installed package version(s) from project/workspace node_modules roots
symbols           List symbols for a package name/version
evidence          Bundled evidence: exact symbol hits + FTS fallback + batched snippets in ONE call

Reference

Flag	Subcommand	Description
--database<PATH>	global	Path to nci.sqlite. Overrides `database` in `nci.config.json`. Available on every subcommand.
--format<plain\|json\|jsonl>	global	Output format for commands that support it. Overrides `format` in `nci.config.json`.
--defaults, -y	init	Accept all defaults — write `nci.config.json` non-interactively.
--version<VERSION>	upgrade	Target release (default: latest). Must be newer than the running engine.
--check	upgrade	Print current vs latest; exit code 3 when an upgrade is available.
--dry-run	upgrade	Show what would run without downloading or migrating.
--skip-db	upgrade	Upgrade the binary only; skip `db migrate`.
--project-root, -r<DIR>	index	Index this directory instead of the one in `nci.config.json`. Defaults to `.`.
--max-hops, -m<N>	index	Re-export resolution depth. `0` = entry only. `-1` = unlimited.
--package, -p<GLOB>	index	Repeatable. Restrict the run to packages matching the glob, on top of `package_scope`.
--dependency-stub-package, -s<PKG>	index	Repeatable. When any crawled file imports this package (or a subpath), record an `npm::…` stub edge instead of walking into it. Unioned with `dependency_stub_packages` from `nci.config.json`.
--package-scope<dependencies\|dev-dependencies\|all-installed>	index	Comma-separated or repeated. `package.json` sections whose names gate indexing. `all-installed` (alone) disables the gate. Overrides `package_scope` in `nci.config.json`.
--skip-root-workspace	index	Skip `<project_root>/node_modules`. Conflicts with `--include-root-workspace`.
--include-root-workspace	index	Force-include `<project_root>/node_modules`. Conflicts with `--skip-root-workspace`.
--dry-run	index	Walk scan and filter only. No SQLite writes. Useful as a CI sanity gate.
--limit, -n<N>default = 20	query find	Cap FTS hits. `--max-rows` does not apply here — that flag is only for `nci sql`.
--package<NAME>	query find	Filter hits to one indexed package name.
--package-version<VERSION>	query find	Filter hits to one indexed package version.
--source-package<NAME>	query find	Filter hits to declarations authored by this source package (the package whose `.d.ts` declared the symbol).
--kind<KIND>	query find	Filter by `kind_name`, e.g. `InterfaceDeclaration`, `FunctionDeclaration`, `ClassDeclaration`.
--file<TEXT>	query find	Filter to hits whose stored `file_path` contains this text.
--public-only	query find	Hide symbols flagged internal to the package export surface.
--limit, -n<N>default = 20	query symbol	Cap exact-name hits.
--package<NAME>	query evidence	Required. Indexed package whose declarations to search.
--package-version<VERSION>	query evidence	Pin to one indexed version.
--source-package<NAME>	query evidence	Filter to declarations authored by this source package.
--symbol<NAME>	query evidence	Repeatable. Exact symbol name to look up. Provide at least one of `--symbol` or `--phrase`.
--phrase<TEXT>	query evidence	Repeatable. FTS phrase to match. Falls back when an exact symbol name is unknown.
--kind<KIND>	query evidence	Apply one literal `kind_name` filter to every anchor — passing the wrong kind returns 0 hits.
--public-only	query evidence	Hide rows where `symbols.is_internal = 1`.
--limit, -n<N>default = 10	query evidence	Cap deduped hits in `data.symbols`.
--snippet-limit<N>	query evidence	Cap how many returned hits get a snippet attached. Default matches `--limit` (1:1 coverage).
--limit, -n<N>default = 100	query symbols	Page size for the paginated symbol listing. Pair with `--offset`.
--offset<N>	query symbols	Skip this many rows before returning.
--max-packages<N>	db backfill	Stop after updating this many packages (default: drain the full pending queue).
--check	db status	Run `PRAGMA quick_check`. Conflicts with `--deep`.
--deep	db status	Run `PRAGMA integrity_check`. Can take minutes on large databases.
--yes, -y	db clear	Skip the confirmation prompt before deleting all rows.
--yes, -y	db remove	Skip the confirmation prompt.
--yes, -y	db remove-glob	Skip the confirmation prompt.
--force	db destroy	Required confirmation. Deletes the SQLite file from disk — no prompt, no recovery.
--schema	sql	Print the `CREATE TABLE` statements for NCI's tables, then exit.
--command, -c<SQL>	sql	One read-only SQL statement to run. Mutating commands (`INSERT` / `UPDATE` / `DELETE` / DDL) are rejected.
--max-rows<N>	sql	Print at most N rows. The command fails if the query would return more than N — useful for asserting query bounds in scripts.

Shell completion

nci

bash, fish, powershell, and elvish are also accepted.

Exit codes are at Exit codes.
Environment variables that affect the CLI are at Environment variables.
The JSON envelope --format json produces is at JSON output schemas.