Start with doctor
neuralinverse doctor
doctor (also /doctor) checks the Node.js version, platform, terminal, configuration folder and source, model, permission mode, git, ripgrep, the sandbox, MCP servers, proxy settings and, when you use Govern, the sign-in state. Then use these to see what is in effect:
| Command | Shows |
|---|
neuralinverse config show | The merged settings, with secrets masked |
neuralinverse config path | The settings files in use |
neuralinverse config validate | Errors in settings files, and keys locked by a managed policy |
/env | Provider variables (set or not), proxy, sandbox, shell, tools on PATH |
/info | Session, model and connection overview |
--debug | Diagnostic details on errors |
--verbose | Progress on standard error with -p; diagnostics for acp and host |
Installation
| Symptom | What to do |
|---|
doctor reports the Node.js version as failed | The npm package needs Node.js 22.19 or newer. Upgrade Node.js, or install the standalone binary |
| The install script stops with a checksum error | The downloaded binary did not match the release's SHA256SUMS, or the file has no entry. Nothing was installed. Check your mirror (NI_DOWNLOAD_BASE) or download again |
| musl-based Linux on arm64 | Only x64 is built for musl. Install with npm |
/update says it does not manage this copy | It updates only npm global installs and binaries in ~/.neuralinverse/bin (or NI_INSTALL_DIR). Update with the tool you installed it with |
| Checks coverage reports an engine error in a standalone binary | The tree-sitter WASM files are missing. Put them in tree-sitter-wasm/ next to the executable or set NEURALINVERSE_TREE_SITTER_WASM |
Providers and models
| Symptom | What to do |
|---|
| The CLI starts setup instead of a session | No usable provider was found. Finish setup, or set a provider variable such as ANTHROPIC_API_KEY |
-p exits with an error naming variables | Non-interactive runs do not start setup. Set one of the named variables, or configure a provider first |
| A key is rejected | Run /provider test to repeat the live check. Setup stores keys in the keychain; on Linux without a Secret Service session they go to ~/.neuralinverse/credentials.json |
| A model is refused with "not allowed by your organization's policy" | Your organisation's policy limits models. Pick one from /model |
The model cell shows ▲ model · reconnecting | A model request failed and is being retried. Press r to retry now, m to switch model, l for the error log |
| Costs look wrong | Costs are estimates from list prices; override pricing per model. Your provider's bill is authoritative |
| Requests fail behind a corporate proxy | Set HTTPS_PROXY (and NO_PROXY), and add your root certificate with NODE_EXTRA_CA_CERTS |
Signing in to Govern
| Symptom | What to do |
|---|
invalid_client at sign-in | The Govern server is older than the per-app clients. The administrator upgrades Govern, or sets keystone.clientId in managed settings |
--issuer is retired: use --base-url <url> | Use neuralinverse login --base-url <url>, or set keystone.baseUrl |
--base-url cannot change it | Your organisation's managed settings fix the Govern address |
| Discovery is refused | An answer was not https, redirected, was not the expected JSON, or named a host outside the base URL's domain. Check keystone.baseUrl |
| The browser sign-in never completes over SSH | The browser must reach the CLI machine's loopback address. Open the URL on that machine, forward the port, or use neuralinverse login --device |
Keystone session expired, run neuralinverse login | Govern refused the token refresh. Sign in again |
| Tokens are kept only in memory | No credential store works on this machine (for example no Secret Service). Sign in again in each process, or set up a Secret Service |
| Signed out unexpectedly | Your device was blocked, revoked or over the device limit (the CLI says which), or you signed out of the Editor or the Agents app, which signs the CLI out at its next start |
neuralinverse policy shows no organisation policy | The current Govern server does not serve the policy route yet; see Sign in to Govern |
| Model calls and tools are refused; the policy is "locked" | The cached organisation policy is past its offline grace or expired, or keys are pinned and no valid policy could be fetched. Run /policy refresh when Govern is reachable |
Permissions
| Symptom | What to do |
|---|
Everything is denied with -p | Nobody can answer in a non-interactive run, so anything that would ask is denied. Grant what the task needs with --mode and --allow |
| A call is refused in every mode | A deny rule, organisation governance, or a blocking checks finding refused it. /rules lists the rules and marks organisation rules |
You are asked even in full-auto | Organisation governance asks for an approval, an ask rule matched, a signed control needs approval, or the tool always asks (such as fw_flash) |
| Headless runs are refused for a missing work item | The governance policy requires an intent. Pass --intent <ref> |
full-auto is not offered | Administrators set permissions.disableFullAuto |
The agent cannot write .neuralinverse/settings.json, .git/ or shell profiles | These always ask unless an explicit allow rule covers them |
| A shell deny rule did not stop something | Shell deny rules are a guard rail, not a security boundary. Use the sandbox for untrusted work |
Sandbox
| Symptom | What to do |
|---|
| A warning says commands run unsandboxed | The sandbox is enabled but unavailable. Install bubblewrap on Linux; macOS uses the built-in sandbox-exec. Set sandbox.required to refuse commands instead |
| A command needs network access in the sandbox | Set sandbox.allowNetwork, or run it outside the sandbox |
| A command cannot write a file | Only the workspace, the temporary folder and sandbox.writablePaths are writable |
| The sandbox fails inside a container | bubblewrap needs user namespaces; on some hosts that means --security-opt seccomp=unconfined |
MCP servers
| Symptom | What to do |
|---|
| A server shows as failed | /mcp shows its status and logs; /mcp reconnect <name> retries. A failing server never blocks the session |
| Slow servers time out | Raise NEURALINVERSE_MCP_TIMEOUT (connect, default 30 seconds) or NEURALINVERSE_MCP_TOOL_TIMEOUT (calls, default 10 minutes) |
| A server needs sign-in | neuralinverse mcp login <name> |
| Every MCP tool asks | Only tools that declare readOnlyHint count as read-only. Add an allow rule such as mcp_github_* |
Checks
| Symptom | What to do |
|---|
| Findings never block | Only signed rule packs and managed checks.block thresholds for signed external findings can block; the baseline pack is advisory |
| A key in the project's settings is ignored | Some checks keys are managed only; a warning names them |
| An engine timeout | Raise checks.budgetMs.agent or .commit. With checks.failClosed a timeout of a signed analyser blocks |
| An existing pre-commit hook | checks hook install keeps it and chains to it; --force replaces it with a backup |
Terminal
| Symptom | What to do |
|---|
Shift+Enter sends instead of starting a new line | Run /terminal-setup, or use Alt+Enter, Ctrl+J, or \ then Enter |
| Colours look wrong | Try "ui": { "theme": "high-contrast" } or "mono"; NO_COLOR and FORCE_COLOR are honoured |
| Animation is distracting | "ui": { "reducedMotion": true } or NO_MOTION=1 |
| You prefer a full-screen interface | Use --fullscreen, or set "ui": { "layout": "fullscreen" } |
Organisation context
| Symptom | What to do |
|---|
| Exit code 5 | You are not signed in, or the session ended. neuralinverse login |
| Exit code 6 | Your organisation refused it, the repository is forbidden by the binding policy, or the feature is off for you |
| Exit code 4 | The decision needs a person on a terminal; it cannot be made from a script or an agent's shell |
| The folder is not bound | neuralinverse context status says why. Only origin, or the branch's tracked remote, is used |
Firmware and HDL
| Symptom | What to do |
|---|
/environment says the setting is ignored | The folder is not a project folder, or the setting was in user-level settings |
| The firmware tools ask before running read-only actions | The project's own files set tool paths or arguments; the CLI asks because a cloned repository could point them anywhere |
| Flashing is denied in CI | Non-interactive runs cannot flash. Flashing always needs a person |
| A probe cannot be reached | Check cables, USB permissions (udev rules on Linux) and power; fw_toolchain lists each tool with its version or an install hint |
Report a problem
/feedback writes a bug report or feedback file to attach to an issue; nothing is sent. Report security problems privately to security@neuralinverse.com, with the version (neuralinverse --version) and your platform.