nmm is the Nelson Modules Manager.

Installations are prepared in a temporary staging directory, built, locked, and then copied to the final user modules directory. If an error occurs before completion, nmm rolls back the partially installed module.

Source module dependencies declared in module.json are resolved before the module is built. When a source module already provides module-lock.json, its exact locked dependency versions are used instead of the declarative ranges. Local paths, archives and HTTP Git repositories are installed recursively. Version constraints are checked against already installed dependencies and conflicts stop the installation before the module is copied. Source installs build the module in staging before committing it to the final modules directory. Package tests are not run at install time by default: pass -tests to run them, or set the environment variable NELSON_NMM_INSTALL_TESTS=1 to run them for every source install; -no-tests is still accepted. A registry entry declaring "tests": "required" always runs the package tests, and the install fails when they do. Prebuilt archives never run tests: they were tested when packed (nmm pack requires passing tests). If a source install fails, an already installed version of the same module remains installed and active.

Source modules and prebuilt archives are validated before installation. Packages whose nelson compatibility range does not match the running Nelson version are rejected before build or final copy.

Source-based distribution packages allows to have optimized packages for your computer and allows to have distributed repositories.

Installed modules are locally built and can require an C/C++.

st = nmm('list') get list of installed modules. This reads the local installed-module registry without network access or package loading and requires only the json module, not webtools or file_archiver. The -json and -quiet forms have the same dependencies.

Add '-json' to list, commands, help, tree, why, deps, outdated or doctor to return the same report encoded as JSON for scripts.

Add '-quiet' as the last argument to suppress command output while preserving returned values. This is intended for CI scripts around commands that run builders or tests.

nmm('commands') returns a short scriptable list of supported command groups, syntax examples and aliases. nmm('help') lists command names. nmm('help', command) returns the entry for one command or alias.

nmm('config') reports the configured registry, cache directory, user modules directory, signing-key state, trusted registry key count, unsigned-registry opt-out and offline cache count.

nmm('install', git_url) install a distant module.

About git_url, in this example 'https://github.com/nelson-lang/module_skeleton_basic.git#v1.0.0'

'#v1.0.0' is defined as #<commit-ish>, it allows to clone exactly an commit.

The commit-ish can be a tag (exact version), and an sha1 (exac commit) or an branch name.

Without commit-ish, master branch will be used.

nmm('install', package_name, version) installs an exact package version or the newest package version matching a semver constraint from the configured registry. The registry entry must contain an install source through source, url or archive. Dependencies declared by the registry entry are resolved recursively before the requested package is installed.

Accepted semver constraints include forms such as >=1.2.0, ~1.4 and ^2.0.0.

Registry installs reject entries whose platforms or nelson metadata are not compatible with the current runtime before reading the package source.

nmm('install', package_name, '-dry-run') resolves the latest compatible registry package. nmm('install', package_name, version, '-dry-run') resolves the registry package and its recursive dependencies, verifies compatibility and local archive checksums when available, and returns an install plan without changing installed modules or the cache.

nmm('install', package_name, version, '-tests') installs a registry package and runs its package tests when its source is a local source tree or a Git repository; -no-tests skips them explicitly (the default, unless the registry entry declares "tests": "required"). nmm('install', package_name, version, '-force') reinstalls the registry package version, replacing an already installed copy when necessary.

nmm('install', filename_nmz) install an prebuilt external module.

Prebuilt archives must contain module-lock.json. Dependencies listed in this lock file must already be installed and the archive platform must match the current architecture or be all. Binary packages also require the locked Nelson architecture and ABI tag to match the running Nelson build. If a sibling .sha256 checksum file exists, it is verified before extraction.

nmm('install', module_path, '-tests') installs a local source module (or a Git repository) and runs its package tests before registering it; nmm('install', module_path, '-no-tests') skips them explicitly. Without an option, tests are not run unless NELSON_NMM_INSTALL_TESTS=1 is set.

nmm('install', package_filename, '-dry-run') verifies an archive install plan without writing to modules.json or copying files into the user modules directory.

nmm('install', package_filename, '-force') reinstalls the same checked archive version by uninstalling the already installed version after the archive dry-run validation succeeds.

nmm('verify', package_filename) verifies a .nmz archive without installing it. It checks package structure, module.json, module-lock.json, embedded lockfile checksums, optional .sha256 sidecar, and Nelson architecture or ABI compatibility for binary packages. nmm('verify', module_path) verifies that a source module lockfile is up to date.

nmm('load', module_name) load an installed module for current session.

nmm('load', module_name, version) loads a specific installed version of a module.

Multiple versions of the same module can be installed side by side. The active version is the newest installed version unless a version has been pinned.

nmm('pin', module_name, version) selects the default active version and records it in modules.json as pinned_version. If the version is omitted, the current active version is pinned.

nmm('unpin', module_name) removes pinned_version without uninstalling the module and makes the newest installed version active.

nmm('why', package_name) explains which installed modules require an installed package by reading installed module-lock.json dependencies. nmm('why', install_report, package_name) explains why a package appears in a registry dry-run install plan.

nmm('tree', package_name) returns the installed dependency tree for a package by reading module-lock.json. nmm('tree', install_report) returns the dependency tree represented by a registry dry-run install plan. The report includes nested dependencies, missing packages and conflicts.

nmm('deps', package_name) and nmm('deps', install_report) return a flat dependency list from an installed package tree or registry dry-run install plan. nmm('rdeps', package_name) returns installed packages that depend on a package. nmm('status', package_name) returns a scriptable summary of the installed package state, active version, lockfile, missing dependencies and reverse dependencies.

nmm('explain', package_name) combines status, dependency tree and reverse dependency information into a scriptable report with human-readable summary lines. nmm('graph', package_name) exports the installed dependency graph as DOT and Mermaid text.

nmm('installed', package_name) returns locally installed versions only. nmm('latest', package_name) returns the latest compatible registry package. nmm('resolve', package_name, version_spec) returns the exact compatible registry version selected for a version constraint without installing it. nmm('satisfies', version, version_spec) checks a version against an exact version or semver constraint.

l = nmm('autoload', module_name returns current state autoload for module_name.

nmm('autoload', module_name, state) marks an installed modules "marked" as autoload at startup.

By default modules are marked as autoload.

nmm('uninstall', module_name) uninstall an installed module.

nmm('remove', module_name) is an alias for nmm('uninstall', module_name). Removal returns a report when requested, including removed paths, reverse dependencies and whether the operation changed installed modules.

nmm('remove', module_name, version) removes only the selected installed version. Without a version argument, all installed versions of the module are removed. nmm('remove', module_name, '-dry-run') reports the impact without deleting files. By default, removal is refused when installed modules still require the package; use -force to remove it anyway.

nmm('orphans') lists auto-installed dependency packages that are no longer reachable from explicitly installed modules. nmm('autoremove', '-dry-run') reports those packages without deleting them, and nmm('autoremove') removes them with explicit force because they are already classified as orphan dependencies. Both commands support '-json' output for scripting.

nmm('package', module_name, destination_dir) packages an module as a zip file.

The generated module-lock.json stores exact installed dependency versions, lock format, package type (source or binary), source metadata, Nelson version, architecture, ABI tag and checksums for key installed files such as module.json, loader.m, builder.m and the startup or finish scripts. The packaged module records the dependency set, runtime context and file integrity state used at build time.

Packaging also writes package_filename.sha256. This sidecar is optional for single-file distribution: installing or publishing a .nmz archive verifies it when present, and otherwise relies on the checksums embedded in module-lock.json.

nmm('pack', module_path, destination_dir) validates and builds a source module in a temporary staging directory, runs the module tests with fail-fast behavior, generates module-lock.json, then creates a .nmz archive and its .sha256 checksum.

nmm('pack', module_path, '-dry-run') validates, builds, tests and computes the lockfile without creating an archive. With a destination directory, the report also includes the archive path that would be written.

nmm('pack', module_path, destination_dir, '-no-tests') creates the archive without running package tests. This is intended for local development archives only.

By default the archive excludes version-control directories, build output (bin/, x64/, object and library files, cmake caches) and editor junk, so a packaged module is clean without any configuration. A .nmignore file at the module root adds further excludes with gitignore-style patterns (# comments, *, **, a trailing / for a directory, a leading ! to re-include, an unslashed name matches at any depth while a slashed pattern is anchored to the module root); a file whose parent directory is excluded cannot be re-included. An optional files array in module.json is an allowlist of glob patterns: when present, only the matching files are packaged (still minus the default excludes, and always keeping module.json, module-lock.json and loader.m). nmm('pack', module_path, '-dry-run') lists the exact files that would be packaged, so the selection can be checked before an archive is written.

nmm('lock', module_path) builds the source loader when needed and writes or refreshes module-lock.json in the source tree without installing or packaging the module. nmm('lock', module_path, '-dry-run') returns the computed lock without writing it. nmm('lock', module_path, '-check') reports whether the current lockfile is up to date. nmm('lock', module_path, '-diff') also returns the current and expected lock data.

nmm('publish', package_filename) publishes a checked .nmz archive into the configured local registry JSON file. It inserts the package metadata from module.json, including summary, description, license, authors, repository, tags and package type when present, plus the source path and SHA-256 checksum, then writes registry.json.sha256. When NELSON_NMM_REGISTRY_SIGNING_KEY holds an Ed25519 private seed (64 hexadecimal characters), it also writes the registry.json.sig sidecar: a JSON document carrying the Ed25519 signature of the exact registry bytes and the matching public key (see crypto.ed25519.sign).

nmm('publish', package_filename, '-dry-run') verifies the archive, reads the target local registry and returns the registry entry that would be written without modifying files. nmm('publish', package_filename, '-check') returns whether publication is currently possible. nmm('publish', package_filename, '-force') explicitly replaces an existing entry with the same package and version. -json returns the publish report as JSON.

nmm('publish', package_filename, '-source', url) stores url (an http or https address, typically a release download link) as the archive source instead of the local packing path. The checksum is still computed from the published local archive, which must be identical to the hosted file. This is how a hosted registry references archives.

A binary (builtin) package is architecture specific, so its archive is stored under an artifacts map keyed by architecture (for example win64 and woa64). Publishing another architecture of the same package version merges it into the same registry entry rather than replacing it, so a single name and version can ship several architectures published at different times; only re-publishing the same architecture needs -force. When a package is installed, the archive matching the running architecture is selected. Source packages keep the platform all and a single source and checksum.

nmm('init', destination_dir, ...) assembles a module.json manifest from name/value fields and sensible defaults, validates it with the same schema validator as validate, and writes it in destination_dir. Defaults: version 1.0.0, platforms {'all'}, nelson >=2.0.0, builtin false, empty dependencies, and module derived from the destination folder name. 'Force', true overwrites an existing manifest, 'DryRun', true returns the struct without writing, 'Skeleton', true also drops a minimal loadable source tree, and 'Interactive', true prompts for missing required fields (disabled by default so --file scripts never block). It also echoes non-fatal best-practice warnings (missing repository, authors, keywords or description) using the same linter as validate -warnings. See nmm init for details.

nmm('validate', module_path) validates the module descriptor before installation or packaging. module_path may be a module directory or a path to a lone module.json file (or any *.json manifest): when a file is passed, only its manifest fields are validated and the source-tree layout checks are skipped.

Validation checks required fields, module name syntax, semantic version syntax, supported platforms, Nelson version compatibility, builtin type, SPDX license expression, dependency declarations, and the source module layout. A valid source module must provide builder.m or loader.m, etc/startup.m, etc/finish.m, help, and tests. Packaging also requires at least one test file and stops when a package test fails.

nmm('validate', module_path, '-strict') also requires publish-oriented metadata such as repository, homepage and non-empty keywords, plus at least one test and XML help file.

nmm('validate', module_path, '-warnings') returns non-blocking warnings for weak package metadata such as missing description, repository, authors or keywords, or placeholder-only help pages. The same recommended-field warnings are surfaced by nmm('init') when generating a manifest.

nmm('validate', module_path, '-json') returns a JSON validation report instead of raising validation errors.

Packaged archives are also checked after build: loader.m and module-lock.json must exist before a .nmz archive is written or installed.

nmm('audit') checks installed module records.

The audit verifies installed paths, module.json, module-lock.json, locked platform compatibility, binary Nelson ABI compatibility, locked dependencies and lockfile checksums. It returns a struct with ok and issues fields.

nmm('audit', package_name) runs the same checks for a single installed package.

nmm('audit', '-json') returns the same audit report encoded as JSON for CI usage.

nmm('doctor') returns the audit report plus Nelson version, architecture, ABI tag, usermodulesdir(), configured registry, cache directory and broken module names.

nmm('doctor', package_name) returns the same diagnostic information for one package and includes its status report.

nmm('repair') removes broken modules.json entries whose installed path is missing. It returns the list of removed entries.

nmm('search', query), nmm('info', package_name) and nmm('versions', package_name) read the configured registry index.

nmm('search', query, '-json'), nmm('info', package_name, '-json') and nmm('versions', package_name, '-json') return JSON output for CI and scripting workflows.

By default search reports the whole registry regardless of the current machine. nmm('search', query, '-platform') keeps only the packages installable on the running architecture (their platforms contains computer('arch') or all); it is opt-in so scripts get machine-independent results by default, and presentation layers such as the package manager window use it to hide packages built for another architecture.

nmm('registry', 'check') verifies the configured registry (local file or remote source), its checksum sidecar and its Ed25519 signature sidecar, then returns a diagnostic report including the signing key, the trusted-key count and, for a remote registry, the cached copy and the offline state.

nmm('registry', 'validate') is an alias for check. nmm('registry', 'stats') returns registry entry counts, unique package counts, platform list and checksum/signature counts. nmm('registry', 'list') returns the configured registry, packages and stats. nmm('registry', 'doctor') combines registry validation with duplicate, missing-source, unsigned and unchecksummed package reports.

The registry source is NELSON_NMM_REGISTRY when set, otherwise registry.json in usermodulesdir(). The source can be a local JSON file or a remote endpoint (http://, https:// or file://). Local registry files must have a registry.json.sha256 sidecar and are verified before they are read; when registry.json.sig is present, its Ed25519 signature must be valid and come from a trusted key. Remote registries are fetched as raw bytes together with registry.json.sig, verified before the JSON is parsed, then cached in the nmm cache directory: when the source is unreachable, the last verified copy is re-verified and used (offline mode). A remote registry without signature is refused unless NELSON_NMM_REGISTRY_ALLOW_UNSIGNED=1 is set (a warning is emitted once per session). Trusted keys are the official Nelson registry keys embedded in Nelson, the keys listed in NELSON_NMM_REGISTRY_PUBLIC_KEY (';' separated, 64 hexadecimal characters each) and the key derived from NELSON_NMM_REGISTRY_SIGNING_KEY. Installing an archive entry also verifies the package checksum before extraction.

nmm('outdated') reports installed modules for which the registry contains a newer semantic version.

nmm('update') updates installed modules to the latest registry version. With a module name, only that module is updated.

nmm('update', module_name, '-dry-run') reports the update plan without modifying installed modules.

nmm('update', '-dry-run') reports the update plan for all installed modules without modifying installed modules.

nmm('cache', 'dir') returns the local archive cache directory and nmm('cache', 'clear') clears it. Installing a checked .nmz archive stores it in the cache.

nmm('cache', 'list') lists offline packages currently available in the local cache.

nmm('cache', 'size') returns archive count and total cached bytes. nmm('cache', 'remove', package_name, version) removes one cached archive and its checksum sidecar.

nmm('cache', 'info', package_name, version) returns the cached archive path, checksum, size and date. nmm('cache', 'has', package_name, version) returns true when that archive is available.

nmm('cache', 'add', package_filename) verifies and preloads a local .nmz archive into the cache. nmm('cache', 'export', destination_dir) copies cached archives and checksum sidecars to a directory. nmm('cache', 'import', source_dir) verifies and imports cached archives from a directory.

nmm('cache', 'verify') verifies cached archives and reports corrupted entries. nmm('cache', 'prune') removes older cached versions while keeping the latest cached version of each package. nmm('cache', 'prune', '-dry-run') reports the same removals without deleting files.

nmm('install', package_name, '-offline') installs the newest cached package version without reading the registry or package source.

nmm('install', package_name, version, '-offline') installs an exact cached package version, or the newest cached version matching a semver constraint, without reading the registry or package source. Add '-dry-run' to verify the cached archive plan without installing it.

ismodulegetmodulesnmm_gui