Skip to content

nsx module

Manages app-local NSX modules.

Subcommands:

  • list
  • describe
  • search
  • add
  • remove
  • update
  • init
  • register
  • validate

nsx module list

nsx module list [--app-dir APP_DIR] [--registry-only] [--json]

Example:

nsx module list --app-dir <app-dir>

Built-in entries come from the packaged NSX registry.

Machine-readable example:

nsx module list --registry-only --json

nsx module describe

nsx module describe [--app-dir APP_DIR] [--json] module

Examples:

nsx module describe nsx-pmu-armv8m --app-dir <app-dir>
nsx module describe nsx-pmu-armv8m --json

describe is intended as the per-module discovery surface for tools and agents. When metadata can be resolved, it includes dependency, compatibility, target, and optional capability information from nsx-module.yaml. Use --app-dir for app-local effective registry resolution.

nsx module search [--app-dir APP_DIR]
                  [--board BOARD] [--soc SOC] [--toolchain TOOLCHAIN]
                  [--include-incompatible] [--json]
                  query

Examples:

nsx module search profiling --app-dir <app-dir>
nsx module search pmu --soc apollo510 --json

search is intended as the query surface for tools and agents. It searches current module metadata such as:

  • module names
  • module type and optional category/provider fields
  • exported CMake targets
  • required and optional dependencies
  • compatibility fields
  • provides.features
  • optional future semantic fields such as capabilities, use_cases, or summary

When --app-dir is provided, NSX uses the app-effective registry and the app's target context by default. Use --include-incompatible if you want to keep non-matching results in the output for comparison or planning.

nsx module add

nsx module add [--app-dir APP_DIR] [--dry-run] module

Example:

nsx module add nsx-peripherals --app-dir <app-dir>

For built-in modules, NSX uses the registry's default upstream repo and revision unless the app overrides that source.

This is the standard way to install a supported first-class module into an app.

nsx module remove

nsx module remove [--app-dir APP_DIR] [--dry-run] module

nsx module update

nsx module update [--app-dir APP_DIR] [--dry-run] [module]

nsx module init

nsx module init [--name NAME] [--type TYPE] [--summary SUMMARY]
                                [--version VERSION]
                                [--dependency DEPENDENCY]
                                [--board BOARD] [--soc SOC] [--toolchain TOOLCHAIN]
                                [--force]
                                module_dir

Examples:

nsx module init my-sensor-driver

nsx module init my-sensor-driver \
    --type backend_specific \
    --summary "I2C driver for the XYZ ambient light sensor." \
    --dependency nsx-core \
    --dependency nsx-i2c \
    --soc apollo510 \
    --soc apollo510b \
    --soc apollo5b

Creates a standard custom-module skeleton with:

  • nsx-module.yaml
  • CMakeLists.txt
  • README.md
  • includes-api/<module_name>/...
  • src/<module_name>.c

Use this as the normal starting point for third-party and app-local modules, then validate and register the generated module.

nsx module register

nsx module register --metadata METADATA --project PROJECT
                    [--project-url PROJECT_URL]
                    [--project-revision PROJECT_REVISION]
                    [--project-path PROJECT_PATH]
                    [--project-local-path PROJECT_LOCAL_PATH]
                    [--app-dir APP_DIR] [--override] [--dry-run]
                    module

Use this when you want to register an external module for one app without editing the packaged registry.

Use this for local filesystem modules and custom git repos that are not part of the built-in NSX catalog.

nsx module validate

nsx module validate [--json] metadata

Examples:

nsx module validate path/to/nsx-module.yaml
nsx module validate path/to/nsx-module.yaml --json

Validates that an nsx-module.yaml file has all required fields and valid values. Use this before registering a custom module to catch errors early.

Checks include:

  • schema_version is 1
  • module.name, module.type, module.version are present and valid
  • module.type is one of the supported types
  • support.ambiqsuite is true
  • build.cmake.package and build.cmake.targets are present and non-empty
  • depends.required and depends.optional are present
  • compatibility.boards, compatibility.socs, compatibility.toolchains are non-empty

Local filesystem example:

nsx module register my-custom-module \
    --metadata /path/to/my-custom-module/nsx-module.yaml \
    --project my_custom_repo \
    --project-local-path /path/to/my-custom-module \
    --app-dir <app-dir>

Git-backed example:

nsx module register my-custom-module \
    --metadata /path/to/my-custom-module/nsx-module.yaml \
    --project my_custom_repo \
    --project-url https://github.com/myorg/my_custom_repo.git \
    --project-revision main \
    --project-path modules/my_custom_repo \
    --app-dir <app-dir>

register writes an app-local override into nsx.yml and then vendors the registered module into that app.

Common Notes

  • --dry-run shows changes without writing
  • compatibility checks are enforced before module mutation