Skip to content

Using the CLI

s edited this page Sep 30, 2026 · 10 revisions

Using the CLI

This page describes sn-module-gen 0.1.3. Run project commands from an existing Supernote plugin root. A feature is an authored module package; it can contain C/C++, Kotlin/Java, or both. Update and validation always cover the project.

Three ways to use it

Guided main menu

sn-module-gen

The menu offers Add feature, Update project, Validate project, Doctor, Help and Exit. Add asks for starter families and package/naming choices, not dependency installation or app builds.

Direct command with prompts

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

In a terminal, missing Add choices are prompted. Update confirms replacement of all generator-owned output, not selection of one module.

Non-interactive command

sn-module-gen add document --starter cpp --yes --plain
sn-module-gen update --yes --plain
sn-module-gen validate --json

--yes accepts documented Add defaults or confirms Update. It is not an option for Validate or Doctor.

Interactive controls

Use arrow keys and Enter in menus, Space for starter selection, Esc to go back, and Ctrl+C to interrupt. Text fields support normal cursor and editing keys. With --plain, menus use numbered choices and accept :back or :cancel. Multi-line input is not accepted where one value is required.

Help and version

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 doctor
sn-module-gen add --help

Installed help is the authority for the version you are running.

Commands

Command Scope
add Scaffold one new authored feature, then generate the complete project
update Regenerate every local feature and shared generated runtime
validate Check the complete project without publishing generated artifacts
doctor Check generator-relevant tools and selected versions
help Show the command overview or help for a supported command

These are the only public commands. There is no check, repair, remove or template command. Dependency installation, app builds and template scripts are author-owned. See Managing Modules for removal.

Add

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

Use a new destination. Add scaffolds source, metadata, package.json and, for native source, an ordinary author-owned CMakeLists.txt. It then generates all current features. It does not invoke npm, Yarn, Git or an app build. It prints a dependency-install command for you to run separately.

Options:

--starter <cpp|kotlin>          repeat to scaffold both families
--description <TEXT>           use "" to omit
--javascript-name <NAME>
--android-namespace <NAME>
--package-version <VERSION>    default: 0.1.0
-y, --yes                     accept documented defaults
-h, --help

cpp creates C++23 source; ordinary C23 helpers may be added behind a marked C++ boundary. kotlin creates Kotlin source; Java may be added alongside it. Starter choice is not a permanent implementation-language restriction.

Non-interactive Add requires a package name. Without --yes, every initial output-affecting choice must be explicit. With --yes, omitted choices use a C/C++ starter, empty description, version 0.1.0 and derived JavaScript/Android names. Explicit options override those defaults.

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

Update

sn-module-gen update --yes

Plain Update discovers every current local module, runs bounded compiler/KSP analysis when JVM source is present, and rewrites all generated output even if the bytes are unchanged. It preserves authored source, metadata, package files and author CMake. It neither refreshes dependencies nor builds the app.

Manual generated edits are overwritten. Obsolete output is removed only inside verified generated ownership; a project with zero modules is valid. There is no module-name argument, selective update, preview or old-output rollback.

Validate

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

Validation checks all authored modules, declared direct dependencies, exported APIs, expected generated files, completion markers and compatibility records. It does not regenerate output, install packages or build the app. Bounded compiler/KSP work may use the designated build scratch area; that scratch is accounted separately from protected project inputs and generated output.

Run Update after source changes, then Validate. Run the app's own build and device tests separately; validation is not proof of app compilation or execution.

Doctor

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

Doctor reports Python/package provenance, Node resolution when dependencies are present, CMake 3.24 or newer, a C23/C++23 compiler, and Java/Kotlin/KSP tools when JVM source is present. It never installs tools, runs the app build, accesses a device or certifies PluginHost/SELinux behavior. It has no implementation-backend selector and no app-build option.

The generated Android SDK CMake default remains 3.24.4. The hosted native minimum qualification pin is 3.24.3 from PyPI; it is not an Android SDK change.

Output modes

--quiet     errors and one final result line
--verbose   complete analyzer output and diagnostics
--json      one versioned machine-readable result
--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. See Error Handling.

Exit codes

Code Meaning
0 Success or user cancellation
1 Operation or validation failure
2 Usage or input error
3 Partial generated output: fix the cause and rerun Update
130 Interrupted with Ctrl+C

For an interrupted Add, follow its specific authored-scaffold instructions; do not overwrite or discard surviving source. See interrupted generation.

Retired options

Version 0.1.3 rejects --all, --build, --build-hook, --dry-run, --diff, --package-manager, --skip-install, --delete-build-files and --jvm-manifest-root. Use plain project-wide Update/Validate and run your chosen package manager and app build yourself. There is no compatibility alias for the retired command forms.

Clone this wiki locally