Firmware and hardware environments

The CLI has two optional developer environments, the same ones the Editor has:

Selecting an environment adds its tools and a short section of the system prompt that tells the agent how to use them; none removes both. The welcome screen shows an Environment cell, and the status bar shows firmware or hardware while one is active.

Maturity

The CLI's firmware and HDL tools reuse the Editor's embedded and HDL modules (tool definitions, CMake presets reader, size report, fault decoder, CTest and Unity parsing, project importer, OpenOCD arguments, GDB/MI layer). Those modules' own records state:

• Embedded: nothing has been run on a board yet. Flashing through J-Link, ST-LINK (STM32CubeProgrammer) or OpenOCD, and debugging, have integration tests written but not yet run. IAR and Keil projects are not yet run against IAR or Keil.
• HDL: the open tools are verified on Linux. No vendor path is verified, nothing is verified on Windows, and no board was programmed in the repository's tests.

The CLI's own documentation records no runs against hardware. Do not rely on flashing, debugging or serial tools for production work until they are verified for your probe, target, tools and operating system. See Domain modules for the Editor's state.

Switch an environment on

An environment is a project setting, chosen by hand:

/environment                 # picker in the interactive interface
/environment embedded        # or: firmware, hdl, hardware, none
neuralinverse env            # show the current environment
neuralinverse env set hdl    # set it from a shell (writes .neuralinverse/settings.json)

Or edit .neuralinverse/settings.json:

{ "environment": "embedded" }

Rules:

• It is never switched on automatically. A folder full of CMake presets, Keil projects or hdl.json still starts with none.
• It is never stored in user-level settings. ~/.neuralinverse/settings.json cannot set it, and /environment --user and neuralinverse env set --user refuse. Managed policy does not set it either.
• It applies only in a project folder: a repository, a folder with a build manifest (CMakeLists.txt, Makefile, package.json and similar), or a folder with hdl.json. Not your home folder. Outside a project the setting is ignored and /environment says why.
• The Editor's switches count. When the CLI setting is absent, neuralInverse.embedded.enabled or neuralInverse.hdl.enabled (or neuralInverse.environment) in the project's .vscode/settings.json select the environment, so a project set up in the Editor works unchanged. An explicit "environment": "none" in .neuralinverse/settings.json turns them off for the CLI.

Settings

The tool settings use the Editor's names: embedded.X.Y in .neuralinverse/settings.json is neuralInverse.embedded.X.Y in .vscode/settings.json, and hdl.X.Y is neuralInverse.hdl.X.Y. Both files are read; the CLI's values win.

Settings that name programs or arguments to run (paths.*, openocd.arguments, the lint and simulation arguments) are "restricted": the Editor honours them only in a trusted workspace. In the CLI, when the project's own files set any of them, the otherwise read-only tools (fw_toolchain, fw_size, hdl_lint) ask before running, since a cloned repository could point them anywhere.

Firmware tools

Every tool runs programs from argument arrays, never through a shell, and answers with a short structured result and, on failure, the next step to take.

Flashing always asks

Flashing hardware always needs a person's approval:

• in every permission mode, including full-auto;
• even when an allow rule matches (fw_flash, fw_*) or a tool.before hook approves;
• "always allow" answers are treated as "once", and no rule is saved.

Policy can still deny it ("deny": ["fw_flash"]), and read-only mode denies it. Non-interactive runs (-p, CI, schedules, helper agents without a person) cannot flash: the call is denied and the agent is told why.

The approval card shows the probe, the target, the image path, its size and its SHA-256. The image is hashed again just before programming; if it changed after you approved (for example, a rebuild in between), nothing is flashed.

Hardware tools

hdl.json is the Editor's project file:

{
  "name": "blinky",
  "sources": ["rtl/**/*.sv"],
  "includeDirs": ["rtl/include"],
  "defines": { "WIDTH": 8, "SIM": true },
  "top": "top",
  "vhdlStandard": "08",
  "buildDirectory": "build/hdl",
  "testbenches": [{ "name": "tb_top", "top": "tb_top", "sources": ["tb/tb_top.sv"], "simulator": "icarus", "timeout": 60 }],
  "targets": [{ "name": "icebreaker", "family": "ice40", "device": "up5k", "package": "sg48", "constraints": "icebreaker.pcf" }]
}

Comments and trailing commas are allowed; unknown keys are errors.

Troubleshooting

• /environment (or neuralinverse env) prints where the current value came from and why an environment is off (not a project folder, or both Editor switches on).
• fw_toolchain and hdl_project list every tool with its version or an install hint.
• Probe problems: fw_flash names the probe software's error and suggests checking cables, USB permissions (udev rules on Linux) and power.