Installation

Install NCI

Install via the Node package (@nativecontextindex/cli), the curl installer, or cargo install from source. All paths give you one nci binary on PATH.

Node package (recommended)

nci

nci is meant to live on your PATH, not in any one project. Install once, use everywhere.

The Node package ships a postinstall script (packages/nci/scripts/postinstall.cjs) that downloads a prebuilt binary from the GitHub release matching the package version. The downloaded binary lives under node_modules/@nativecontextindex/cli/vendor/.

Postinstall escape hatches

NCI_SKIP_DOWNLOAD=1 — skip the download (use the binary already on PATH, or your own build).
NCI_DOWNLOAD_BASE_URL=<url> — override the GitHub release base URL (mirrors, internal proxies).
NCI_BINARY=/abs/path/to/nci — make the Node shim and nci-mcp defer to a specific binary at runtime.

See Environment variables for the complete list.

Install without npm

nci

Uses npm install -g when npm is on PATH; otherwise installs the native binary to ~/.local/bin (add that directory to PATH). Pin a version with NCI_VERSION=0.2.0.

Upgrading

nci

Installs the latest release, replaces the native binary, and runs db migrate on your configured database. If a migration defers symbol work, run nci db backfill or nci index afterward — upgrade does not run backfill automatically. Pin with nci upgrade --version 0.2.0 (must be newer than nci --version).

Pinning an older version

nci

There is no nci downgrade command. Installing an older npm version re-downloads the matching binary when vendor/.nci-version differs. If the database schema was migrated forward, an older engine may refuse to open it until you stay on the newer release or reset the database.

From source (Cargo)

nci

The Rust crate is nci-engine; the resulting binary is nci. After install, point the Node shim at the local build:

nci

Verify

nci

binary-path (alias which) prints the absolute path of the running nci executable. That value is exactly what to paste into NCI_BINARY when wiring up nci-mcp.

If both verify steps succeed, jump to Quickstart.