Using the CLI

Using the CLI

supernote-module works as both a guided terminal application and a normal scriptable command. Run it from the root of an existing Supernote plugin.

The CLI calls each independently managed module package a feature. That module can use the native C/C++ environment, the Kotlin/Java JVM environment, or both.

Three ways to use it

Guided main menu

Run the command without a subcommand:

supernote-module

This opens:

Add feature
Update feature
Validate feature
Remove feature
Doctor
Help
Exit

This is the easiest way to discover the tool and select an existing feature.

Direct command with prompts

Provide the action and, if useful, a feature name:

supernote-module add
supernote-module add document
supernote-module update
supernote-module validate document

When standard input and output are connected to a terminal, the CLI asks for missing decisions. Running supernote-module add document still gives you the starter, naming, package-manager, and installation prompts; it only skips the main menu and package-name question.

Non-interactive command

For a script or CI job, provide every required decision or use --yes where the command has documented safe defaults:

supernote-module add document --starter cpp --yes --plain
supernote-module update document --yes --plain
supernote-module validate document --build --json

--yes does not mean “say yes to everything.” It accepts only that command's documented defaults. It never silently selects all features or deletes build output.

Interactive controls

In a capable terminal:

Key	Action
Up or Down	Move through a menu
Space	Select or clear an item in the starter multi-select
Enter	Accept the highlighted choice or displayed text default
Esc	Go back one question; from the main menu, leave the program
Left or Right	Move inside a text field
Home or End	Move to the beginning or end of a text field
Backspace or Delete	Edit the current field
Ctrl+C	Interrupt and exit with code 130

The CLI rejects multi-line text where one value is expected.

When cursor control is unavailable, or when you pass --plain, menus become numbered lists. For a multi-select, enter numbers separated by commas. Use:

:back
:cancel

to move backward or cancel.

Help and version

The installed help is the authority for the version you actually have:

supernote-module --version
supernote-module --help
supernote-module help add
supernote-module help update
supernote-module help validate
supernote-module help remove
supernote-module help doctor

The option form also works:

supernote-module add --help

Commands

Command	What it does
add	Creates and links one local feature
update	Regenerates owned files while preserving implementation source
validate	Checks one or all features and can run the Android build
remove	Permanently removes one or all managed features
doctor	Checks the plugin and development environment
help	Shows command help

Except for Doctor's basic environment report, useful project operations must run from a valid plugin root.

Add

Usage

supernote-module add [PACKAGE] [options]

The important V2 choice is which environment to scaffold, not a permanent backend:

supernote-module add document --starter cpp
supernote-module add document --starter kotlin
supernote-module add document --starter cpp --starter kotlin

• cpp creates a C++ example. C23 files can be added under the same native source root.
• kotlin creates a Kotlin example. Java files can be added under the same JVM source root.
• Repeating --starter creates both examples.

A C++ starter does not stop the module from gaining the JVM environment later, and a Kotlin starter does not make it a JVM-only module.

Add options

--starter <cpp|kotlin>          repeat to create both starters
--description <TEXT>            use "" to omit it explicitly
--javascript-name <NAME>        generated feature name
--android-namespace <NAME>      Java-style package namespace
--package-version <VERSION>     default: 0.1.0
--package-manager <npm|yarn>
--skip-install
--build
--yes

In the guided flow, suggested names and the package version appear inline. Press Enter to accept a suggestion or type over it. Add runs after the final valid answer; there is no separate “Are you sure?” screen.

What --yes chooses

In non-interactive use, the package name is always required. Without --yes, every output-affecting decision must be provided, including at least one starter.

With --yes, Add uses these defaults when you did not provide another value:

starter             C/C++
description         omitted
package version     0.1.0
JavaScript name     derived from the package name
Android namespace   derived from the package name
install dependency  yes

If both npm and Yarn lockfiles exist, the CLI does not guess. Pass --package-manager npm or --package-manager yarn.

Name inference

For normal package names, the CLI removes an initial react-native- or local-, removes a trailing -plugin, and splits the remaining words on hyphens, underscores, dots, and tildes.

For example, local-document-tools can suggest:

JavaScript name:   DocumentTools
Android namespace: com.example.document_tools

Explicit options always win. Invalid or colliding names fail before the generator changes the plugin.

What --skip-install means

Add always writes the local dependency to package.json. --skip-install only skips the npm or Yarn command and lockfile refresh.

After using it, run the project's package manager yourself before imports or validation that depend on node_modules:

npm install

or:

yarn install

A complete automated Add

supernote-module add @acme/document \
  --starter cpp --starter kotlin \
  --javascript-name Document \
  --android-namespace com.acme.document \
  --package-version 0.1.0 \
  --package-manager npm \
  --yes --plain

Update

Usage

supernote-module update [FEATURE] [options]

Update refreshes generated files for one feature while preserving its C/C++ and Kotlin/Java implementation roots.

supernote-module update document
supernote-module update document --build
supernote-module update document --yes --plain

Before changing anything, the interactive command shows what it will replace, what it will preserve, and which parent-plugin files will change. Confirmation defaults to Yes.

Options:

--package-manager <npm|yarn>
--skip-install
--build
--yes

Dependency installation runs only when package metadata or the local link needs refreshing.

After changing marked declarations, include the Android generation/build path before trusting index.d.ts:

supernote-module update document --yes
supernote-module validate document --build

Validate

Usage

supernote-module validate [FEATURE] [options]
supernote-module validate --all [options]

A normal validation checks structure, ownership metadata, local package links, and shared-runtime integration:

supernote-module validate document
supernote-module validate --all

Add --build when you need the Kotlin, KSP, CMake, NDK, JNI, and TypeScript generation path to run:

supernote-module validate document --build --verbose

Interactive validation asks whether to build and defaults to No. --all collects every feature failure before returning failure.

A successful build proves that generation and compilation worked in that environment. It does not prove execution in a particular PluginHost or firmware.

Remove

Usage

supernote-module remove [FEATURE] [options]
supernote-module remove --all [options]

Remove is intentionally harder to trigger than Add or Update.

Interactive removal of one feature requires typing its exact package name:

supernote-module remove document

Removing every managed feature requires the exact phrase REMOVE ALL:

supernote-module remove --all

For automation, the target must already be unambiguous:

supernote-module remove document --yes --plain
supernote-module remove --all --yes --plain

supernote-module remove --yes without a feature or --all is rejected.

Build output is preserved by default, including when --yes is present. To remove the three documented build directories too, opt in separately:

supernote-module remove document --delete-build-files --yes

That option targets exactly:

build/
android/build/
android/app/build/

It does not delete arbitrary caches or widen a one-feature removal to every feature.

The transaction keeps implementation source recoverable until parent changes, dependency refresh, and postcondition checks succeed. If removal is interrupted, follow the recovery guidance before editing generated state by hand.

Doctor

supernote-module doctor
supernote-module doctor --verbose
supernote-module doctor --json

Doctor checks the JavaScript, Android, Kotlin/KSP, C23/C++23, NDK, CMake, Gradle, and JSI requirements used by V2's plugin-level runtime.

It deliberately has no Native/JNI/JSI selector. JSI and JNI are generated routes, while the developer chooses the native environment, the JVM environment, or both inside one module.

Doctor does not use ADB and cannot certify target-device runtime behavior.

Output modes

Operational commands support:

--quiet     errors and one final result line
--verbose   complete subprocess output and diagnostics
--json      one versioned machine-readable result object
--no-color  no ANSI color
--plain     line-oriented ASCII interaction
--debug     internal diagnostics and tracebacks

--quiet, --verbose, and --json are mutually exclusive. JSON mode is non-interactive. Automation should parse JSON rather than human-formatted text.

Exit codes

Code	Meaning
0	Success or user cancellation
1	Operation, validation, or build failure
2	Usage or input error
3	Partial completion that requires recovery
130	Interrupted with Ctrl+C

Cancellation is not an error. Exit code 3 is different: read and follow the reported recovery instructions before starting another manual repair.

Useful workflows

Explore everything interactively

supernote-module

Add a C++ feature with normal defaults

supernote-module add local-math --starter cpp --yes

Add Kotlin now and C++ too

supernote-module add document --starter kotlin --starter cpp --yes

Generate without running npm or Yarn yet

supernote-module add document --starter kotlin --skip-install --yes

Regenerate and compile after changing markers

supernote-module update document --yes
supernote-module validate document --build --verbose

Check every managed feature in CI

supernote-module validate --all --json

See the complete failing Android command

supernote-module validate document --build --verbose