---
title: "Settings reference"
---

# Settings reference

The CLI's settings files, how they are layered and merged, every top-level settings key, the environment variables it reads, and how to move settings between machines.

Settings files are JSON with comments and trailing commas allowed. For completion and validation in your editor, add:

```json
{ "$schema": "<settings-schema-url>" }
```

| Command | What it does |
|---|---|
| `neuralinverse config validate` | Check every settings file; show which keys a managed policy locks |
| `neuralinverse config show` | Print the merged result, with secrets masked |
| `neuralinverse config path` | List the files in use |
| `/config` | Settings in effect and where they came from, in a session |

## Layers

From lowest to highest precedence:

| Layer | Location |
|---|---|
| User | `~/.neuralinverse/settings.json` (`NEURALINVERSE_CONFIG_DIR` moves the whole folder) |
| Project, shared | `.neuralinverse/settings.json`; commit it |
| Project, personal | `.neuralinverse/settings.local.json`; do not commit it |
| Extra files | `--config <file>` (repeatable) |
| Command line | `--model`, `--mode`, `--allow`, `--deny`, `--max-turns`, `--reasoning`, `--mcp-config` |
| Managed policy | The managed settings file, the remote policy, and the organisation's signed policy. See [Enterprise deployment](https://neuralinverse.com/docs/cli/enterprise/) |

Objects merge key by key; later layers win. These lists are combined across layers instead of replaced: `permissions.allow`, `permissions.ask`, `permissions.deny`, `permissions.additionalDirectories`, `sandbox.writablePaths` and `webFetch.deniedDomains`.

A managed layer locks every top-level key it sets. Some keys are honoured only in certain layers; the table below says so.

## Keys

| Key | Type | Description |
|---|---|---|
| `model` | string | Default model, `provider/model` |
| `smallModel` | string | Cheaper model for summaries; alias for `models.fast` |
| `models` | object | Model per role: `main`, `plan`, `fast`, `subagent`, `summary`, `vision`. See [Providers and models](https://neuralinverse.com/docs/cli/models/#models-per-role) |
| `fallback` | object | `models`, `on`, `cooldownMs`. See [fallback models](https://neuralinverse.com/docs/cli/models/#fallback-models) |
| `budget` | object | `perPrompt` and `perSession` limits, `warnAt`. See [budgets](https://neuralinverse.com/docs/cli/models/#budgets) |
| `providers` | object | Provider definitions. See [Providers and models](https://neuralinverse.com/docs/cli/models/#configure-a-provider) |
| `maxOutputTokens` | number | Output token limit per response (default 16384, capped by the model) |
| `temperature` | number | Sampling temperature where supported |
| `reasoning` | `off`, `low`, `medium`, `high` | Reasoning effort |
| `outputStyle` | string | `default`, `concise`, `explanatory`, `review`, or a custom style from `styles/*.md` |
| `promptCaching` | boolean | Provider prompt caching (default true) |
| `maxTurns` | number | Model calls per prompt (default 200) |
| `permissions` | object | `mode`, `allow`, `ask`, `deny`, `additionalDirectories`, `disableFullAuto`. See [Permissions and modes](https://neuralinverse.com/docs/cli/permissions/) |
| `sandbox` | object | `enabled`, `allowNetwork`, `writablePaths`, `required` |
| `hooks` | object | Event to list of `{matcher, command, timeoutMs}`. See [Hooks](https://neuralinverse.com/docs/cli/hooks/) |
| `mcpServers` | object | MCP server definitions. See [MCP servers](https://neuralinverse.com/docs/cli/mcp/) |
| `env` | object | Extra environment variables for commands the agent runs |
| `compaction` | object | `auto` (default true), `threshold` (fraction of the context window, default 0.85) |
| `bash` | object | `defaultTimeoutMs` (120000), `maxTimeoutMs` (600000), `maxOutputChars` (30000), `shell` |
| `webFetch` | object | `allowedDomains`, `deniedDomains`, `maxBytes` |
| `instructionFiles` | string[] | Instruction file names (default `["AGENTS.md", "NEURALINVERSE.md"]`) |
| `audit` | object | `enabled`, `path`. See [Enterprise deployment](https://neuralinverse.com/docs/cli/enterprise/#audit-log) |
| `telemetry` | object | Opt-in OpenTelemetry export. See [Enterprise deployment](https://neuralinverse.com/docs/cli/enterprise/#opentelemetry) |
| `ui` | object | `layout` (`fullscreen`, `inline`), `transcript` (`gutter`, `numbered`), `theme` (`dark`, `light`, `auto`, `high-contrast`, `mono`), `reducedMotion`, `showThinking`, `markdown`, `color`, `vimMode`, `statusLine: {command, timeoutMs}` |
| `agents` | object | `maxBackground`: concurrent background helper agents (default 4) |
| `tools` | object | `deferThreshold` (40), `repl` (true), `profile` (`auto`, `edit`, `patch`, `both`), `batchedReads` (true), `fuzzyEdits` (true). See [Tools](https://neuralinverse.com/docs/cli/tools/) |
| `prompt` | object | `version`: `v1` (default) or `v2` |
| `harness` | object | `loopDetection` (true), `stallTurns` (8), `autoContinue` (true), `maxAutoContinues` (2), `effortRouting` (false) |
| `worktree` | object | `directory`: where `worktree` creates checkouts (default `.neuralinverse/worktrees`) |
| `services` | object | `memory` (`enabled`, `maxNotes`), `notifications` (`enabled`, `minDurationMs`), `keepAwake`, `suggestions` (`true`, `false`, `"model"`), `tips` |
| `sessionRetentionDays` | number | Delete saved sessions older than this (default 30; 0 keeps them forever) |
| `lsp` | object | `enabled`, `disabled` (server names), `servers` (custom language servers) |
| `verify` | object | `enabled`, `mode` (`off`, `suggest`, `auto`), `checks`, `timeoutMs`, `maxRounds`. See [Tools](https://neuralinverse.com/docs/cli/tools/#verification-after-edits) |
| `plugins` | object | Plugin name to `false` to disable an installed plugin for this project |
| `index` | object | `enabled`, `maxFiles` (50000), `repoMapTokens` (1500; 0 = no map), `embeddings: {provider, model}` (off; sends code to that provider) |
| `team` | object | `enabled`, `maxTasks` (6), `concurrency` (3). See [Goals, team runs and schedules](https://neuralinverse.com/docs/cli/autonomy/) |
| `goals` | object | `checkpointEvery`, `continuationPrompt`, `maxIterations` (25) |
| `context` | object | Context window management. See [Sessions and context](https://neuralinverse.com/docs/cli/sessions/#keep-long-sessions-inside-the-context-window) |
| `voice` | object | Voice input for `/voice` (below) |
| `environment` | `none`, `embedded`, `hdl` | Project only; never read from user settings or managed policy. See [Firmware and hardware environments](https://neuralinverse.com/docs/cli/environments/) |
| `embedded` | object | Firmware tool settings, using the Editor's names |
| `hdl` | object | HDL tool settings, using the Editor's names |
| `checks` | object | The change gate. Several keys are managed only. See [Checks](https://neuralinverse.com/docs/cli/checks/#settings) |
| `governance` | object | Managed only: `policyBundle`, `policyKeys`, `organisation`. See [Permissions and modes](https://neuralinverse.com/docs/cli/permissions/#where-the-governance-policy-comes-from) |
| `intent` | string | The work item this session serves, for policies that require one (user settings) |
| `contextPlatform` | object | `enabled`, `tokenBudget`, `sourceKinds`, `defaultSpaceId`. See [Organisation context](https://neuralinverse.com/docs/cli/organisation-context/) |
| `workspaceBindingPolicy` | object or string | Managed only. See [Organisation context](https://neuralinverse.com/docs/cli/organisation-context/#the-workspace-binding) |
| `toolEnvironment` | object | Managed only: `secretNames`, `passThrough` |
| `keystone` | object | `baseUrl`, `clientId` (managed only), `policy`, `policyKeys` (managed only), `requireSignIn` (managed only). `issuer` and `apiUrl` are retired. See [Sign in to Govern](https://neuralinverse.com/docs/cli/sign-in/) |
| `activity` | object | `enabled`, `required` (managed), `content` (managed), `endpoint`, `tokenCommand`, `exclude`, `maxQueueBytes`, `maxQueueEvents`. See [Activity record](https://neuralinverse.com/docs/cli/activity/) |
| `remotePolicyUrl`, `remotePolicyRequired`, `remotePolicyPublicKey`, `remotePolicyTokenCommand` | | Managed settings file only. See [Enterprise deployment](https://neuralinverse.com/docs/cli/enterprise/#remote-policy) |
| `embed` | object | Managed only: `hostPolicyPublicKeys`, `trustHostPolicy`. See [SDK, server and embedding](https://neuralinverse.com/docs/cli/sdk/#governance-in-a-host) |

## Voice input

`/voice` records from the microphone until you stop talking (about 1.5 seconds of silence) or a time limit, transcribes the recording and sends the text as your next message. Audio is sent only to the provider named in `voice.provider`; nothing is sent unless `voice` is set.

```jsonc
"voice": {
  "provider": "openai",   // an OpenAI-compatible provider (OpenAI, Groq, a local whisper server) or Gemini
  "model": "whisper-1",
  "language": "en",       // optional ISO-639-1 hint
  "maxSeconds": 60,       // longest recording (default 60)
  "silenceMs": 1500,      // quiet after speech that ends the recording (default 1500)
  "device": "hw:1"        // optional input device
}
```

Recording uses a program already on the system: SoX (`rec`) or ffmpeg on macOS; `arecord`, ffmpeg or SoX on Linux; ffmpeg on Windows. The audio is kept in a temporary WAV file only until it is transcribed.

## Move settings between machines

```bash
neuralinverse settings export bundle.json         # settings, keybindings, commands, agents, skills, styles
neuralinverse settings import bundle.json         # merged into ~/.neuralinverse (--replace overwrites settings)
neuralinverse settings sync --repo git@host:me/ni-settings.git   # two-way sync; the URL is remembered
```

Bundles and the sync repository never contain secrets: `apiKey`, every `headers` map, OAuth `clientSecret` and secret-looking `env` entries are removed, and only the files listed above are copied (never credentials, sessions, caches, logs or plugins). Importing keeps this machine's keys. Sync clones the repository into `~/.neuralinverse/sync`, copies changes in the right direction, commits and pushes. When a file changed on both sides, this machine's copy wins; for `settings.json` both versions are merged, this machine's values winning.

## Environment variables

| Variable | Effect |
|---|---|
| `NEURALINVERSE_CONFIG_DIR` | Use another configuration folder instead of `~/.neuralinverse` |
| `NEURALINVERSE_MANAGED_SETTINGS` | Path of the managed settings file |
| `NEURALINVERSE_MANAGED_SETTINGS_URL` | Remote policy URL when the managed file sets none |
| `NEURALINVERSE_MANAGED_SETTINGS_TOKEN` | Bearer token for the remote policy request |
| `NEURALINVERSE_AUDIT_LOG` | Audit log path (turns auditing on) |
| `NEURALINVERSE_DISABLE_UPDATE_CHECK=1` | Skip the daily check for a newer version (also skipped when `CI` is set) |
| `NEURALINVERSE_MCP_TIMEOUT`, `NEURALINVERSE_MCP_TOOL_TIMEOUT` | MCP connect and call timeouts (ms) |
| `NEURALINVERSE_SEARCH_ENGINE=js` | Use the built-in search instead of ripgrep |
| `NEURALINVERSE_TELEMETRY=1` | Turn on OpenTelemetry export (with the standard `OTEL_*` variables) |
| `NEURALINVERSE_SERVER_TOKEN` | Token for `neuralinverse serve` |
| `NEURALINVERSE_SHARED_DATA_DIR`, `NEURALINVERSE_IDE_QUALITY` | Where the Build apps' shared account link lives, and the build quality (default `stable`) |
| `NEURALINVERSE_TREE_SITTER_WASM` | Folder of the checks engine's tree-sitter WASM files |
| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS` | Network proxy and certificates |
| `BRAVE_SEARCH_API_KEY`, `TAVILY_API_KEY`, `SEARXNG_URL` | Turn on the `web_search` tool with that backend |
| `NO_COLOR`, `FORCE_COLOR` | Colour output |
| `NO_MOTION=1` | Reduced motion |

Provider credential variables are listed in [Providers and models](https://neuralinverse.com/docs/cli/models/#providers-that-need-no-configuration).

## Files written

| Path | Contents |
|---|---|
| `~/.neuralinverse/settings.json` | Your settings |
| `~/.neuralinverse/keybindings.json` | Key bindings |
| `~/.neuralinverse/credentials.json` | Provider keys, only when no keychain works (mode 0600) |
| `~/.neuralinverse/projects/<workspace>/` | Sessions, checkpoints, memory, code index, spill files |
| `~/.neuralinverse/history.jsonl` | Prompt history |
| `~/.neuralinverse/cache/models-*.json` | Model lists from providers (24 hours) |
| `~/.neuralinverse/audit/*.jsonl` | Audit log, when enabled |
| `~/.neuralinverse/managed/remote-policy.json` | Last good copy of the remote policy |
| `~/.neuralinverse/managed/keystone-policy.json` | Last verified organisation policy |
| `~/.neuralinverse/keystone/session.json` | Non-secret facts about your Govern sign-in |
| `~/.neuralinverse/activity/queue/<account>/` | Activity events waiting to be sent |
| `~/.neuralinverse/plugins/` | Installed plugins |
| `~/.neuralinverse/server.json` | URL and token of a running `serve` (mode 0600; removed on shutdown) |
| `~/.neuralinverse/sync/`, `sync-state.json` | Settings sync work tree and state |