Plugin Dev - nself-org/plugins GitHub Wiki
Plugin author tools: scaffold, link, run with hot reload, debug and test a plugin under development. Free — MIT licensed.
nself add plugin-devNo license key required.
The author commands that used to live in core as nself plugin init|new|dev|debug|link|unlink|test now ship as this free
CLI plugin. Authors add the plugin, then run the commands as nself plugin-dev <command>. Behaviour is the same as core:
same flags, messages, exit codes and file effects.
This is a CLI plugin: it installs the nself-plugin-dev binary into your plugin path and runs as a command, not a
background service. Category: development.
| Command | What it does |
|---|---|
nself plugin-dev init <name> |
Scaffold a plugin project. Flags: --template go|rust|node|static, --tier free|pro, --bundle, --description, --author, --category, --min-cli, --min-sdk, --port, --out, --force, --tenancy, --no-interactive. Alias: scaffold. |
nself plugin-dev new <name> |
Deprecated alias of init; prints the deprecation notice. |
nself plugin-dev link <path> |
Record a local plugin directory (it must hold a plugin.yaml) in ~/.nself/plugin-links.json so nself build prefers it. --host, --list. |
nself plugin-dev unlink <name> |
Remove the link. Unlinking an unlinked plugin is a no-op. |
nself plugin-dev dev <name> |
Auto-link, then run the hot-reload watcher (air, or fswatch). --no-link, --debug, --entrypoint. |
nself plugin-dev debug <name> |
Build the plugin with debug flags and run it under a headless dlv on a port in 2345-2399. --port, --port-only. |
nself plugin-dev test <name> |
Unit tests, then a smoke install and uninstall. --phase unit|smoke|both, --host, --no-cleanup. |
Every subcommand takes --json. plugin-dev printed no JSON before, so there is no legacy shape: the v1 envelope
(schema_version, command, then data or error) is printed in both v1.4 and v1.5 mode. With --json stdout carries
that one document and nothing else; status lines, child process output and the launch.json snippet go to stderr. Without
--json the output is unchanged. A failure prints an error envelope and exits with its class status (user 1, infra 2);
a child process's own exit status is reported in error.cause, not as the exit status.
| Command |
data fields |
|---|---|
init, new
|
name, template, tier, tenancy, dir, files (sorted) |
link |
name, path, mode (container-mount or host-process) |
link --list |
links: list of {name, path}, sorted by name |
unlink |
name, unlinked (false when it was not linked) |
dev |
name, plugin_path, linked, debug, entrypoint (printed only when the child process itself exits; a Ctrl+C that signals the whole process group ends plugin-dev with no envelope) |
debug |
name, port, address; plus plugin_path, binary unless --port-only (printed only when the child process itself exits, as for dev) |
test |
name, phase, passed, cleanup
|
Error codes (plugin-owned range E770 to E779, plus E401 for usage): E401 usage, E770 plugin not found, E771 not a plugin directory, E772 scaffold destination not empty, E773 plugin tests failed, E774 plugin-links.json unreadable or unwritable, E775 scaffold failed, E776 a build, debugger, watcher or install step failed, E779 unexpected. Messages are fixed text and never echo a path, flag value or environment value.
| Env Var | Default | Description |
|---|---|---|
NSELF_LOCAL_URL |
http://localhost:8080 |
Base URL test polls for /healthz during the smoke phase. |
nself plugin-dev init my-plugin --tier free --no-interactive
nself plugin-dev link ./my-plugin
nself plugin-dev dev my-plugin
nself plugin-dev test my-plugin --phase unit --host-
--helpshowsnself plugin-dev <command>where core showsnself plugin <command>. -
dev --debugre-runs this binary asdebug, andtestfindsnselfonPATHfor the smoke phases. -
link --listis sorted by name.