CLI and Configuration

CLI and Configuration

The shamoo executable is supplied by @shamoo/cli and requires Node.js 22 or newer. Run it through the project's package manager, for example pnpm exec shamoo .... Success returns exit code 0; invalid input, diagnostics, compilation failures, and stale generated bindings return 1.

Project commands

These are the exact current command forms:

shamoo create <directory> [--name <package>] [--platform paper,velocity]
shamoo doctor [--project <directory>] [--json]
shamoo build [--project <directory>]
shamoo deploy [--project <directory>] [--paper <directory>] [--velocity <directory>]
shamoo dev [--project <directory>] [--paper <directory>] [--velocity <directory>]

• create refuses an existing target, writes source/configuration/package files, and deliberately does not install dependencies or run lifecycle scripts. Its default platform is Paper.
• doctor checks Node, shamoo.config.json, the TypeScript project, the common entrypoint, and configured deployment roots. Missing deployment configuration is a warning; an invalid or unwritable configured target is an error. --json is suitable for CI and editors.
• build runs TypeScript diagnostics and compiler discovery, writes dist/shamoo.metadata.json by default, and creates one independent ESM bundle and external source map per configured platform.
• deploy builds first and writes a complete Runtime installation under each watched root. CLI target options override config targets.
• dev performs an initial build/deploy, watches src and shamoo.config.json, debounces changes, prevents overlapping builds, and queues one follow-up build if files change during a build. Stop with SIGINT or SIGTERM.

A normal Paper workflow is:

pnpm exec shamoo create my-plugin --name @example/my-plugin --platform paper
pnpm exec shamoo doctor --project my-plugin
pnpm exec shamoo build --project my-plugin
pnpm exec shamoo deploy --project my-plugin \
  --paper /srv/paper/plugins/ShamooRuntime/plugins
pnpm exec shamoo dev --project my-plugin \
  --paper /srv/paper/plugins/ShamooRuntime/plugins

For both platforms:

pnpm exec shamoo create network-plugin \
  --name @example/network-plugin --platform paper,velocity
pnpm exec shamoo deploy --project network-plugin \
  --paper /srv/paper/plugins/ShamooRuntime/plugins \
  --velocity /srv/velocity/plugins/shamooruntime/plugins

The deploy paths are ShamooRuntime watched roots, never the servers' general plugins/ directories. Each platform gets <watched-root>/<unscoped-package-name>/shamoo-plugin.json, shamoo.metadata.json, and <platform>/index.js plus index.js.map.

shamoo.config.json

{
  "name": "@example/identity",
  "displayName": "Example Identity",
  "version": "0.1.0",
  "platforms": ["paper", "velocity"],
  "entrypoint": "src/plugin.ts",
  "paperEntrypoint": "src/paper.ts",
  "velocityEntrypoint": "src/velocity.ts",
  "tsconfig": "tsconfig.json",
  "outDir": "dist",
  "permissions": {
    "builtins": [],
    "filesystem": { "read": [], "write": ["./data"] },
    "network": false,
    "workers": false,
    "childProcess": false,
    "nativeAddons": false,
    "nms": false,
    "packets": false
  },
  "communication": {
    "services": [],
    "events": [],
    "consumers": []
  },
  "compatibility": {
    "api": "^0.1.0",
    "runtime": "^0.1.0",
    "minecraft": "1.21.8",
    "paperApi": "1.21.8",
    "velocityApi": "3.4.0"
  },
  "deploy": {
    "paper": "/srv/paper/plugins/ShamooRuntime/plugins",
    "velocity": "/srv/velocity/plugins/shamooruntime/plugins"
  }
}

name, non-empty unique platforms, and entrypoint are required. tsconfig defaults to tsconfig.json, outDir to dist, descriptor version to 0.1.0, and descriptor compatibility to API/Runtime ^0.1.0 with unrestricted host API ranges unless explicitly set. Source, tsconfig, entrypoint, and output paths must be project-relative and may not escape through .. or symlinks. Deploy paths may be absolute or project-relative.

Permissions are requests and build-time declarations, not proof that a Runtime grants them. Every Node builtin import must be listed. Sensitive builtins also require the corresponding capability. node:module, node:repl, and node:vm are unsupported. See Runtime and Security.

Communication entries have these shapes:

{
  "services": [
    {
      "id": "example/economy",
      "version": "2.1.0",
      "componentId": "src/plugin.ts#EconomyPlugin",
      "methods": ["balance"]
    }
  ],
  "events": [{ "id": "example/balance-changed", "version": "1.0.0" }],
  "consumers": [
    {
      "id": "example/economy",
      "versionRange": "^2.0.0",
      "dependentReload": "keep-running"
    }
  ]
}

dependentReload is exactly keep-running or reload. The bundled adapter publishes declared providers but currently has no public service-acquisition facade; read Cross-Plugin Communication before treating declarations as end-to-end wiring.

Other commands

shamoo paper [sync|diff] [paper|paper-nms|paper-packets] [model|-] [output]
shamoo velocity [sync|diff] [model|-] [output]
shamoo migrate winter <source-directory> [--json]
shamoo help
shamoo version

sync deterministically writes generated bindings, diff returns 1 on drift, generate aliases sync, and - selects the pinned model. The Winter command performs a source-only audit without compiling, executing, following symlinks, or rewriting Java.

Source: CLI implementation and command reference.