Skip to main content

neutron-cli

A deliberately small tool. It reads package files from disk, prepares them with the same shared installer helpers the browser uses, combines their Motoko modules and manifests, and writes Wasm and Candid to paths you choose.

That is the entire feature set.

What it is for​

Inspecting exactly what a set of packages compiles to, without a browser and without a replica. Useful for CI checks, reproducibility verification, and answering "does this combination of apps even build".

It requires at least one package input and both output paths.

neutron compile \
  --package kernel.v0.3.5.neutron \
  --package app.v0.1.0.neutron \
  --wasm-out neutron.wasm \
  --candid-out neutron.did

--package may be repeated. --vetkeys-environment production is optional and is the only accepted environment value.

What it deliberately is not​

The CLI does not install, uninstall, upgrade, bootstrap, discover canisters, manage identities, proxy, or deploy. Those responsibilities were removed from it on purpose:

  • In-product installs belong to the kernel's browser installer, because they are a reviewed, state-preserving transaction that needs the user's consent and the live canister's current module set.
  • Deployment belongs to neutron-provision, because it needs the verified root context, session state, and asset restore path.

Production context only​

The CLI compiles in the production context. The compiler-pinned IC mainnet root key supplies the trusted installation identity that becomes the actor's immutable installation.network_id.

A local compile is rejected. This is not an oversight: only the attached provisioner can authenticate and supply the exact PocketIC root key for the running instance, and the assembler will not accept a guessed or provisional value for a network identity that is then persisted immutably.

The legacy-named --vetkeys-environment option accepts only production for the same reason.