Developer CLI

The binary name of the @evoxapp/plugin-cli package is evox-plugin.

Installation

Node.js 20+ is required. You can use it with npx without installing:

npx @evoxapp/plugin-cli init my-plugin

or install it globally:

npm install -g @evoxapp/plugin-cli
evox-plugin init my-plugin

Language

CLI messages and init templates (README, comments, action names, key titles) are produced in English or Turkish. The language is chosen in this order: --lang en|tr > EVOX_PLUGIN_LANG > LC_ALL > LC_MESSAGES > LANG > the system locale (tr if it is Turkish) > en. The C and POSIX locales do not count as a language choice. An invalid --lang value returns PLUGIN_CLI_LANG_INVALID; an invalid EVOX_PLUGIN_LANG value is ignored. Error codes and JSON output field names do not change with the language. Template values follow the selected language: for example the author name is Yerel Geliştirici with --lang tr and Local Developer with --lang en. The examples on this page show the English template.

Commands

# init: proje iskeleti (iki hedef)
evox-plugin init ./my-plugin --name "Plugin Adı"                      # sandbox-js (public T2 hedefi, varsayılan) — evox-plugin.json
evox-plugin init ./my-plugin --runtime trusted-node --name "Plugin"   # T1 yerel gelistirme — manifest.json + runtime.mjs

# build/run/sandbox-test yalnız sandbox-js (T2) projeleri içindir; evox-plugin.json gerektirir.
evox-plugin build ./my-plugin
evox-plugin run ./my-plugin
evox-plugin sandbox-test ./my-plugin

# validate/pack/publish-check iki hedefte de çalışır (T1 için aşağıdaki bölüme bakın).
evox-plugin validate ./my-plugin
evox-plugin pack ./my-plugin
evox-plugin publish-check ./my-plugin

--plugin-id <uuid> is optional; if not given, it is generated automatically and shown in the output.

T1 (trusted-node) or T2 (sandbox-js)? The two init targets have different flows:

T1 · --runtime trusted-node → produces manifest.json + runtime.mjs. It is loaded directly from the evoX Plugins → Developer window; local development needs no CLI command. build/run/sandbox-test do not work in this project. validate, publish-check and pack package the project for Market review (the Preparing a T1 project for Market review section below). Steps: Quickstart.
T2 · default (sandbox-js) → produces the evox-plugin.json config. The validate → sandbox-test → build → pack → publish-check pipeline is for these projects (the publication target once public upload opens).

Command	Target	Result
`init`	—	Creates a starter project (default `sandbox-js`/T2; T1 with `--runtime trusted-node`)
`validate`	T2, T1	T2: checks the manifest, paths and dependency inventory; T1: checks `manifest.json`
`build`	T2	Produces a single browser-compatible ESM bundle with esbuild
`run`	T2	Runs a host-validation preview
`sandbox-test`	T2	Sandbox compatibility check: scans the source for Node/DOM/direct network access, validates the browser bundle, exits non-zero on a violation
`pack`	T2, T1	Creates an `.evoxpack` with the `evox-archive-v1` policy
`publish-check`	T2, T1	Runs a local parity check; writes no package

A T1 (trusted-node) project does not use these commands during local development; you develop it by reloading from the Developer window as you change code.

run is not a sandbox. The real T2 boundary is verified in the host-owned Electron sandbox.

sandbox-test is a static compatibility check: it scans your sandbox-js source for Node/DOM/direct network (fetch/WebSocket/XHR) access and validates the browser bundle. Run it before submitting for publication; any violation produces a fail-closed non-zero exit (suitable for CI/pre-submit). The real T2 security boundary is the host-owned Electron Chromium Worker; sandbox-test complements it and does not replace it.

`evox-plugin.json` (sandbox-js/T2 config)

The root config file of a sandbox-js project. init produces it; the pipeline commands (validate/build/pack/publish-check) read it. (This file does not exist in a T1 trusted-node project; T1 works directly with manifest.json + runtime.mjs.)

Field	Description
`schemaVersion`	Config schema version (`1`)
`sourceEntry`	Plugin source entry file (e.g. `src/plugin.ts`); `build` compiles it into a single ESM bundle
`package.name` / `package.description`	Package metadata
`package.author.id` / `package.author.name`	Developer identity (locally `local-developer` / `Local Developer`)
`plugin`	Host manifest (identity, runtime `sandbox-js`, permissions, actions) — for fields see Manifest

dependencies.json is kept separately and inventoried by validate/pack. publish-check does not replace moderation, a production scanner, signing or revocation. As long as public executable upload is not ready, PLUGIN_UPLOAD_NOT_READY is kept.

Preparing a T1 project for Market review

A T1 (trusted-node) plugin enters the Market as a single unminified ESM file; the review reads the code in that file. First:

Add the platforms field to manifest.json, plus declaredCommands for every program the plugin runs and declaredPaths for every system path it touches (see Manifest).
Run npm install in the project folder. @evoxapp/plugin-sdk must be installed in the project and package-lock.json must exist; the integrity of dependencies is read from it.

evox-plugin validate ./my-plugin
evox-plugin publish-check ./my-plugin
evox-plugin pack ./my-plugin

publish-check compiles the runtime entry in manifest.json together with its dependencies into a single file, compares that file with the declarations and writes the findings. It produces no package.
pack turns a project that passes the same checks into an .evoxpack. The package carries three files: plugin/manifest.json, plugin/dependencies.json produced from package-lock.json, and plugin/runtime/plugin.mjs.

If there is an error finding, no package is produced:

Code	Reason
`PLUGIN_CLI_TRUSTED_PLATFORMS_REQUIRED`	The `platforms` field is missing
`PLUGIN_CLI_NATIVE_MODULE_FORBIDDEN`	A `.node` file, `binding.gyp` or `process.dlopen`
`PLUGIN_CLI_INSTALL_SCRIPT_FORBIDDEN`	A bundled dependency has a `preinstall`/`install`/`postinstall` script
`PLUGIN_CLI_DYNAMIC_CODE_FORBIDDEN`	`eval`, `new Function` or the `vm` module
`PLUGIN_CLI_DYNAMIC_REQUIRE_FORBIDDEN`	A `require` that loads anything other than a Node builtin
`PLUGIN_CLI_DYNAMIC_IMPORT_FORBIDDEN`	An `import()` that loads anything other than a Node builtin
`PLUGIN_CLI_CHILD_PROCESS_UNDECLARED`	`child_process` is used but there are no `declaredCommands`
`PLUGIN_CLI_COMMAND_UNDECLARED`	The bundle runs a program outside `declaredCommands`
`PLUGIN_CLI_LOCKFILE_REQUIRED`	There are dependencies but no `package-lock.json`
`PLUGIN_CLI_DEPENDENCY_INTEGRITY_MISSING`	`package-lock.json` has no sha512 integrity for a dependency
`PLUGIN_CLI_ANALYSIS_LIMIT_EXCEEDED`	The bundle exceeds an analysis limit: larger than 16 MB, or too many `child_process` aliases, calls or system paths

Warnings do not stop the package but are listed under warnings in the output: a call whose command name is built at runtime (PLUGIN_CLI_COMMAND_UNRESOLVED), running through a shell (PLUGIN_CLI_SHELL_EXECUTION), a declared command that is not in the bundle (PLUGIN_CLI_COMMAND_UNUSED), a system path outside declaredPaths (PLUGIN_CLI_PATH_UNDECLARED), child_process.fork (PLUGIN_CLI_FORK_USED) and worker_threads (PLUGIN_CLI_WORKER_THREADS_USED).

These checks are only an aid; they are not proof of safety. The packaged plugin is still not a sandbox and runs with the user’s rights. T1 Market upload is still closed: publish-check returns publishable: false and TRUSTED_PLUGIN_UPLOAD_NOT_READY.

Getting started

Core concepts

Examples and distribution

Installation

Language

Commands

`evox-plugin.json` (sandbox-js/T2 config)

Preparing a T1 project for Market review

​Installation

​Language

​Commands

​evox-plugin.json (sandbox-js/T2 config)

​Preparing a T1 project for Market review

Installation

Language

Commands

`evox-plugin.json` (sandbox-js/T2 config)

Preparing a T1 project for Market review