arcane-fvtt CLI

A local Foundry VTT operation CLI that gives agents stable, narrow, observable runtime primitives.

Read the CLI docsJoin the waitlist

Check state with one command

$ npm run fvtt:cdp -- doctor
$ npm run fvtt:cdp -- combat-snapshot
$ npm run fvtt:cdp -- execute-turn --json '@turn.json'

Core features

Turn Protocol v2

Only three input modes: selected-targets, self, and placed-template. Enum parameters are orthogonal to target mode, so there is no hidden fourth mode.

Four-state receipts

completed / rejected / partial / indeterminate. Writes return token diffs, chat cards, and timing so the agent never guesses state.

Allowlist security boundary

Normal commands use an allowlist; debug-eval is only enabled when ARCANE_FVTT_DEBUG_EVAL=1 is set. Arbitrary eval never enters the main flow.

Token-diff observability

Every write returns tokenDiffs, itemCardId, warnings, and timings. Results are auditable, replayable, and comparable.

Get the CLI

The CLI currently ships with the ArcaneDesk development distribution. Install its dependencies, then run npm run fvtt:cdp -- doctor. A standalone npm package is on the roadmap.

Read the CLI docs

Sample execute-turn response

{
  "status": "completed",
  "sourceTokenId": "pNPz2V5cFKYZmzds",
  "actionKey": "greatsword.attack",
  "targetTokenIds": ["SUnqlZmNomEYNOzh"],
  "tokenDiffs": [
    {
      "_id": "SUnqlZmNomEYNOzh",
      "system.attributes.hp.value": -12
    }
  ],
  "itemCardId": "KxG8p2mQvLrT5wFj",
  "warnings": [],
  "timings": {
    "totalMs": 1847
  }
}