Reference · Env vars

Environment variables

Every environment variable the CLI, MCP server, or postinstall script honours. Values shown here come straight from the engine source — there are no “hidden” toggles outside this list.

CLI runtime

Variable	Read by	Effect
`NCI_CACHE_DIR`	`nci`	Override the OS cache directory under which NCI resolves the default SQLite path. Used as a fallback when `database` in `nci.config.json` and `--database` are both absent.
`NCI_BANNER`	`nci`	Controls the boot banner. Accepts `auto`, `on`, `off`. Invalid values are rejected with a CLI error.
`NCI_PROGRESS`	`nci`	Controls the progress display during indexing. Same values as `NCI_BANNER`.
`NCI_SLOW_QUERY_MS`	`nci` (`query --format json`)	Minimum `meta.durationMs` before `meta.suggestions` may appear on a low-yield query. Default: `750`. See Query JSON meta.
`NCI_PROFILE`	`nci` (when built with `phase-profile` feature)	`1` emits crawl phase timings to stderr. Off by default and unavailable in standard release builds.

MCP / Node shim

Variable	Read by	Effect
`NCI_BINARY`	`nci-mcp` · `@nativecontextindex/cli`	Absolute path to the native `nci` binary the shim should call. Highest-priority resolver step — wins over bundled and on-PATH binaries. Find a real path with `nci binary-path`.

Postinstall (Node package only)

Variable	Effect
`NCI_SKIP_DOWNLOAD`	`1` tells the postinstall script not to download the prebuilt binary. Useful in offline CI or when you ship your own build.
`NCI_DOWNLOAD_BASE_URL`	Override the GitHub release base URL used to fetch the prebuilt binary (postinstall and `nci upgrade`).
`NCI_GITHUB_REPO`	Override the GitHub `owner/repo` used by `nci upgrade` and `install.sh` (default: `oyerindedaniel/native-context-index`).
`NCI_VERSION`	Pin a release for `install.sh` / `install-direct.cjs` (default: `latest`).
`NCI_INSTALL_DIR`	Target directory for curl install without npm (default: `~/.local/bin`).