Using the CLI

Using the CLI

sn-module-gen 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:

sn-module-gen

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:

sn-module-gen add
sn-module-gen add document
sn-module-gen update
sn-module-gen validate document

When standard input and output are connected to a terminal, the CLI asks for missing decisions. Running sn-module-gen 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:

sn-module-gen add document --starter cpp --yes --plain
sn-module-gen update document --yes --plain
sn-module-gen 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:

sn-module-gen --version
sn-module-gen --help
sn-module-gen help add
sn-module-gen help update
sn-module-gen help validate
sn-module-gen help check
sn-module-gen help repair
sn-module-gen help remove
sn-module-gen help template
sn-module-gen help doctor

The option form also works:

sn-module-gen 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
check	Compares all generated state with the semantic source of truth
repair	Previews or applies one complete canonical generation plan
remove	Permanently removes one or all managed features
template	Reports or synchronizes official-template launch scripts
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

sn-module-gen add [PACKAGE] [options]

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

sn-module-gen add document --starter cpp
sn-module-gen add document --starter kotlin
sn-module-gen 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

sn-module-gen 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

sn-module-gen update [FEATURE] [options]

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

sn-module-gen update document
sn-module-gen update document --build
sn-module-gen 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:

--all
--dry-run
--diff
--package-manager <npm|yarn>
--skip-install
--build
--yes

--all selects the complete managed project. --dry-run computes the full affected closure without writing, and --diff includes the owned-content diff in that preview:

sn-module-gen update --all --dry-run --diff

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:

sn-module-gen update document --yes
sn-module-gen validate document --build

Validate

Usage

sn-module-gen validate [FEATURE] [options]
sn-module-gen validate --all [options]

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

sn-module-gen validate document
sn-module-gen validate --all

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

sn-module-gen 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.

Check

sn-module-gen check
sn-module-gen check --build

Check is the authoritative read-only comparison of semantic inputs, the integrity manifest, plugin wiring, and every generator-owned artifact. Use it when you need to know whether the project is already canonical. --build adds the Android compilation path after integrity and syntax checks pass.

The --build-hook and --jvm-manifest-root forms belong to generated Gradle integration. Normal project and CI use should call sn-module-gen check.

Repair

Repair previews one complete canonical transaction by default:

sn-module-gen repair --dry-run
sn-module-gen repair --dry-run --diff

Apply that plan only with an explicit --yes:

sn-module-gen repair --yes

Repair lists both requested and transitively affected targets. It never changes user-owned C/C++, Kotlin, or Java source. A successful repair followed by sn-module-gen check should be a true no-op.

Template

Template status is read-only:

sn-module-gen template status

Synchronization previews by default and applies only with --yes:

sn-module-gen template sync --dry-run
sn-module-gen template sync --yes

Sync accepts only a recognized official-template baseline and refuses unknown drift. It changes the versioned Bash and PowerShell launch capability, not arbitrary project scripts.

Remove

Usage

sn-module-gen remove [FEATURE] [options]
sn-module-gen remove --all [options]

Remove is intentionally harder to trigger than Add or Update.

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

sn-module-gen remove document

Removing every managed feature requires the exact phrase REMOVE ALL:

sn-module-gen remove --all

For automation, the target must already be unambiguous:

sn-module-gen remove document --yes --plain
sn-module-gen remove --all --yes --plain

sn-module-gen 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:

sn-module-gen 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

sn-module-gen doctor
sn-module-gen doctor --verbose
sn-module-gen doctor --json
sn-module-gen doctor --build --json

Doctor checks the JavaScript, Android, Kotlin/KSP, C23/C++23, NDK, CMake, Gradle, and JSI requirements used by the generator'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 selects an ADB executable and runs adb version as an advisory host-tool probe. It does not connect to a device or certify PluginHost or tablet behavior. --build adds the authoritative read-only state check and the complete Gradle/KSP/Kotlin/CMake/JNI/JSI build probe.

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

sn-module-gen

Add a C++ feature with normal defaults

sn-module-gen add local-math --starter cpp --yes

Add Kotlin now and C++ too

sn-module-gen add document --starter kotlin --starter cpp --yes

Generate without running npm or Yarn yet

sn-module-gen add document --starter kotlin --skip-install --yes

Regenerate and compile after changing markers

sn-module-gen update document --yes
sn-module-gen validate document --build --verbose

Check every managed feature in CI

sn-module-gen validate --all --json

Prove generated state is canonical

sn-module-gen check --json
sn-module-gen repair --dry-run --diff

See the complete failing Android command

sn-module-gen validate document --build --verbose