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

# Asagidaki pipeline komutlari SANDBOX-JS (T2) projeleri icindir; evox-plugin.json gerektirir.
# T1 (trusted-node) projesi bunlara IHTIYAC DUYMAZ, dogrudan evoX'e yuklenir (asagidaki Note'a bakin).
evox-plugin validate ./my-plugin
evox-plugin build ./my-plugin
evox-plugin run ./my-plugin
evox-plugin sandbox-test ./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; validate/build/pack are not needed. If you run validate in this project you get an error because evox-plugin.json cannot be found — this is expected. 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	Checks the manifest, paths and dependency inventory (requires `evox-plugin.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	Creates an `.evoxpack` with the `evox-archive-v1` policy
`publish-check`	T2	Runs a local parity check

A T1 (trusted-node) project does not use these pipeline commands; 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.

Getting started

Core concepts

Examples and distribution

Installation

Language

Commands

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

​Installation

​Language

​Commands

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

Installation

Language

Commands

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