CLI and Automation

CLI and Automation

Use the guided interface for first use and explicit subcommands for repeatable work. Installed help is authoritative for exact grammar:

supernote-module help add

Commands

Command	Purpose
supernote-module	Guided Add/Update/Validate/Remove/Doctor menu
add	Create and link one local module
update	Refresh generated files while preserving implementation roots
validate	Check structure, integration, links, and optionally Android build
remove	Permanently delete one or all managed packages
doctor	Probe generator and build prerequisites
help	Show stable command help

Global options

Option	Effect
-h, --help	Show help
-V, --version	Show installed version
--quiet	Keep warnings/errors and one final result line
--verbose	Stream subprocess output and diagnostics
--json	Emit one schema-versioned JSON document and never prompt
--no-color	Disable color; NO_COLOR is also respected
--plain	Use line-oriented ASCII interaction/output
--debug	Include internal diagnostics and unexpected tracebacks

--quiet, --verbose, and --json are mutually exclusive. Plain mode has no ANSI cursor control, animation, Unicode-only meaning, or elapsed-time text.

Add

supernote-module add [PACKAGE] [options]

Options: --type <native|jni|jsi>, --description, --javascript-name, --android-namespace, --package-version, --package-manager <npm|yarn>, --skip-install, --build, and --yes.

Non-interactive Add requires PACKAGE. Without --yes, every output-affecting decision must be explicit. With --yes, type defaults to Native, description is omitted, names are derived when valid, version defaults to 0.1.0, and dependency installation is enabled. Conflicting lockfiles still require an explicit package manager.

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

Update

supernote-module update [MODULE] [options]

Options: --package-manager <npm|yarn>, --skip-install, --build, and --yes. Update always targets one module and cannot convert its type. Read Managing Modules before automating it.

Validate

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

Use either one module or --all. Plain validation is structural; --build adds the parent Android assemble task.

Remove

supernote-module remove [MODULE] [options]

Options: --all, --package-manager <npm|yarn>, --skip-install, and --yes. Outside an interactive terminal, --yes is required and valid only with an explicit module or --all. Removal deletes user source too.

Doctor

supernote-module doctor [--type <all|native|jni|jsi>]

Doctor defaults to strict all. Missing generator/build requirements fail it; device and SELinux observations are advisory. Doctor validates prerequisites for generated modules, not the surrounding plugin workflow.

Automation examples

Human-readable, non-interactive:

supernote-module add local-math --type native --yes --plain
supernote-module validate local-math --build --plain

Machine-readable:

supernote-module add local-math --type native --yes --json
supernote-module validate --all --json

Scripts should use an explicit subcommand, inspect the exit status, and parse JSON rather than normal human wording.

Exit codes

Code	Meaning
0	Success, help/version, empty state, or deliberate cancellation
1	Operation, verification, build, Doctor, or internal failure
2	Usage or supplied-input error
3	Partial completion or recovery still required
130	Interrupted before mutation or after successful rollback

Human progress uses stderr and final success uses stdout. JSON uses stdout only when a result document can be constructed.