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