> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evox.wraithesports.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer CLI

> Create, validate, bundle, preview and package a plugin project.

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:

```bash theme={}
npx @evoxapp/plugin-cli init my-plugin
```

or install it globally:

```bash theme={}
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

```bash theme={}
# 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.

<Note>
  **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: <a href="/en/sdk/quickstart">Quickstart</a>.
  * **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).
</Note>

| 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 **reload**ing from the **Developer** window as you change code.

<Warning>`run` is not a sandbox. The real T2 boundary is verified in the host-owned Electron sandbox.</Warning>

`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 <a href="/en/sdk/manifest">Manifest</a> |

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.