Using the CLI

Using the CLI

supernote-module is a command-line application with both a guided menu and direct commands.

Three ways to run it

Guided main menu

Run the command without a subcommand:

supernote-module

This opens the main menu:

Add module
Update module
Validate module
Remove module
Doctor
Help
Exit

This is the easiest way to discover the tool and choose an existing module.

Direct command with prompts

Provide the action, and optionally a module name or some options:

supernote-module add
supernote-module add local-math
supernote-module update
supernote-module validate local-math

When standard input and output are connected to a terminal, missing decisions are requested interactively.

For example:

supernote-module add local-math

can ask for the module type, description, JavaScript name, Android namespace, version, package manager, and whether to install.

This is still normal interactive CLI use. It only skips the main menu.

Non-interactive command

When the command runs without an interactive terminal, or when --json is used, the CLI cannot ask questions.

Provide every required decision, or use --yes where the command supports documented defaults:

supernote-module add local-math --type native --yes
supernote-module update local-math --yes
supernote-module remove local-math --yes

--yes does not mean “answer yes to every possible question.” It accepts the command's documented safe defaults and bypasses the confirmation described by that command.

Interactive controls

In a capable terminal:

Key	Action
Up or Down	Move through a menu
Enter	Select the highlighted item or accept a displayed default
Esc	Go back one step; from the main menu, exit
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 input in fields that expect one value.

When cursor controls are unavailable, or when --plain is used, menus become numbered lists. Type a number to select an item. Use:

:back
:cancel

to move backward or cancel.

Help and version

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

These help screens are part of the installed package and are the authority for the installed version.

The equivalent option form also works:

supernote-module add --help

Commands

Command	Purpose
add	Create and link a local module
update	Refresh generated parts while preserving the implementation root
validate	Check module structure, integration, dependency linking, and optionally the Android build
remove	Permanently delete one or all managed modules
doctor	Check the plugin and development environment
help	Show the command overview or command-specific help

All commands except doctor must run from the Supernote plugin root. Doctor can report that the current directory is invalid, but its useful project checks also require the plugin root.

Add

Usage

supernote-module add [PACKAGE] [options]

In a terminal, both of these are interactive:

supernote-module add
supernote-module add local-math

A typical fully specified command is:

supernote-module add local-math \
  --type native \
  --javascript-name Math \
  --android-namespace com.example.math \
  --package-version 0.1.0 \
  --package-manager yarn \
  --yes

Add options

Option	Meaning
`--type native	jni
--description TEXT	Package description; use "" to omit explicitly
--javascript-name NAME	React Native or JSI object name
--android-namespace NAME	Java-style Android namespace
--package-version VERSION	Initial semantic version; default 0.1.0
`--package-manager npm	yarn`
--skip-install	Create and link the module without running npm or Yarn
--build	Run an Android build after generation and verification
-y, --yes	Accept the documented defaults

What --yes chooses

For Add, --yes supplies these defaults when they were not provided:

• Module type: Native Module.
• Description: omitted.
• Package version: 0.1.0.
• JavaScript name: derived from the package name when valid.
• Android namespace: derived from the package name when valid.
• Install: enabled.

The package name is still required in non-interactive use.

When both package-lock.json and yarn.lock exist, the CLI will not guess. Provide --package-manager npm or --package-manager yarn.

Name inference

The CLI derives names from the unscoped package name. It removes an initial react-native- or local-, removes a trailing -plugin, splits on common separators, and joins the words.

For example:

Package:          local-stroke-math
JavaScript name: StrokeMath
Namespace:       com.example.stroke_math

Explicit options override inferred values.

What --skip-install means

--skip-install skips the npm or Yarn command. It does not skip generation, the package.json dependency change, or other parent integration.

After using it, run the package manager already used by the plugin:

npm install

or:

yarn install

Update

Usage

supernote-module update [MODULE] [options]

Running without a module in a terminal opens a module selector:

supernote-module update

A direct update is:

supernote-module update local-math

Update displays a plan showing what will be replaced, preserved, and changed in the parent plugin. Interactive confirmation defaults to Yes.

Options:

Option	Meaning
`--package-manager npm	yarn`
--skip-install	Skip a required dependency refresh
--build	Run an Android build after verification
-y, --yes	Accept the displayed update plan

Update always targets one module. It does not rename the package, module type, JavaScript name, Android namespace, or package version.

There is no Update dry run or file-by-file diff. See Managing Modules.

Validate

Usage

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

Examples:

supernote-module validate local-math
supernote-module validate local-math --build
supernote-module validate --all
supernote-module validate --all --build --verbose

Without --build, validation checks:

• Managed-module metadata.
• Required generated files.
• Parent package.json integration.
• Gradle integration where applicable.
• The installed local dependency link.
• Export discovery and generated declarations.

With --build, it also runs the applicable Android build.

When Validate is started interactively, it asks whether to run a build. The default is No.

--all reports every module failure before returning a nonzero exit code.

Remove

Usage

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

Remove permanently deletes the complete generated package, including the implementation source that Update normally preserves.

Interactive removal requires typing the exact package name. Removing every module requires typing:

REMOVE ALL

Examples:

supernote-module remove
supernote-module remove local-math
supernote-module remove local-math --yes
supernote-module remove local-math --delete-build-files --yes
supernote-module remove --all --yes

Options:

Option	Meaning
--all	Remove every managed module
--delete-build-files	Also delete plugin build files and compiled binaries
`--package-manager npm	yarn`
--skip-install	Skip the dependency refresh
-y, --yes	Bypass typed confirmation for an explicit target

--yes is rejected when no module and no --all target were provided.

Interactive Remove asks whether to delete plugin build files and compiled binaries after selecting the module. It defaults to No. Use --delete-build-files with --yes for the same cleanup in a script. The cleanup removes build/, android/build/, and android/app/build/ when they exist.

Doctor

Usage

supernote-module doctor [options]

Examples:

supernote-module doctor
supernote-module doctor --type native
supernote-module doctor --type jni
supernote-module doctor --type jsi

doctor without a type strictly checks the requirements for every module type.

Scopes:

Scope	Checks
native	Plugin, Node.js, npm or Yarn, Java, Android SDK, Gradle wrapper
jni	Native checks plus CMake and Android NDK
jsi	JNI toolchain checks plus a runtime-policy advisory
all	Every required check

Doctor can prove that the local generation and build requirements are present. It cannot prove JSI runtime support on a target device.

Global output options

Global options can be used with any command.

Option	Output
--quiet	Errors and one final result line
--verbose	Complete subprocess output and diagnostics
--json	One versioned JSON object and no prompts
--no-color	Human output without color
--plain	Line-oriented ASCII output
--debug	Internal diagnostics and tracebacks for failures

--quiet, --verbose, and --json cannot be combined.

Human output

The default output is intended for a terminal. It uses cursor controls, color, Unicode symbols, and progress animation when the terminal supports them.

Plain output

Use --plain in a basic terminal, when capturing readable logs, or when Unicode and cursor control are undesirable:

supernote-module doctor --type native --plain

Plain interactive menus use numbered choices rather than arrow-key selection.

Verbose output

Use --verbose after the concise error has identified a Gradle, compiler, linker, package-manager, or subprocess failure:

supernote-module validate local-math --build --verbose

JSON output

--json disables prompting and emits one JSON object with schema version 1.0.

The result can include:

schema_version
tool_version
command
status
exit_code
duration_ms
module or modules
changes
dependency
validation
doctor
rollback
warnings
recovery
error

Example:

supernote-module validate --all --json

Use the process exit code for success or failure. Do not decide only from whether JSON was printed.

Debug output

--debug may include internal tracebacks and transaction diagnostics. Use it when reporting an unexpected internal error, not as the normal first step for a build failure.

Exit codes

Code	Meaning
0	Success or deliberate cancellation
1	Operation, verification, Doctor, or build failure
2	Invalid command, option, input, or missing non-interactive decision
3	Partial completion requiring recovery
130	Interrupted with Ctrl+C

When exit code 3 appears, follow the recovery command shown by the CLI before manually deleting recovery files.

Useful terminal workflows

Create a module but keep choosing interactively

supernote-module add local-math

Create a Native Module with defaults

supernote-module add local-math --type native --yes

Generate without running npm or Yarn yet

supernote-module add local-math --type native --skip-install --yes

Validate every managed module

supernote-module validate --all

Capture machine-readable validation

supernote-module validate --all --json > module-validation.json

See the complete failing Android build

supernote-module validate local-math --build --verbose