Commands

The arcane-fvtt CLI commands are grouped by responsibility: connection/debugging, read-only state, world-maintenance primitives, and combat-write primitives.

Connection and debugging

tabs
login
doctor
wait-ready
screenshot
bring-front
canvas-click
debug-eval
profile-execute-turn
  • login: select and log in to a Foundry account by display name or user ID inside the controlled Chrome.
  • doctor: check world, system, module, GM, and combat readiness.
  • debug-eval: a manual debugging back door, disabled by default. Only runs when ARCANE_FVTT_DEBUG_EVAL=1 is set.

Read-only state

world-info
scene-snapshot
combat-snapshot
actor-search
actor-get
actor-export
token-details
token-actions
build-combat-catalog
combat-context
list-catalog-actions
verify-catalog
refresh-token-actions
action-result
  • world-info: returns the current world, system, module versions, and activation status.
  • combat-snapshot / scene-snapshot: read full snapshots of combat or scene state.
  • build-combat-catalog: build a token catalog from the current scene for use with combat-context.
  • combat-context: return the current combatant’s action contract following Turn Protocol v2.

World-maintenance primitives

asset-upload
actor-create-from-compendium
actor-import
actor-update
actor-damage-migrate
actor-bilingual-sync
actor-add-items
actor-add-items-from-compendium
actor-set-image
  • asset-upload: upload a local image into Foundry data storage.
  • actor-create-from-compendium: clone an NPC from a compendium and patch it on creation.
  • actor-damage-migrate: audit legacy attack damage bonuses against a strict manifest and save full rollback snapshots locally.
  • actor-bilingual-sync: audit or sync bilingual actor rules data and overwrite unlinked token synthetic Actors/ActorDeltas.

Combat-write primitives

create-token
delete-token
use-action
execute-turn
use-catalog-action
apply-token-state
start-combat
next-turn
advance-turn
  • execute-turn: submit an action following Turn Protocol v2 and receive a four-state receipt.
  • apply-token-state: directly apply token HP/effect state changes.
  • start-combat / next-turn / advance-turn: combat lifecycle control commands.

Character-sheet entry primitives

When you need to prove the character-sheet entry path, use activity-ui-click. It opens the default dnd5e character sheet, switches to the spell or item tab, locates the activity-use control for the Item/Activity, and sends a real CDP mouse event. The returned receipt.isTrusted must be true:

{
  "actorIdentifier": "Wave B QA Caster",
  "itemIdentifier": "guiding-bolt",
  "activityIdentifier": "cast",
  "targetTokenIds": ["Wave B QA Fail A"]
}
npm run fvtt:cdp -- --port 9230 --target-url http://127.0.0.1:30000 activity-ui-click --json '@activity-click.json'

To prove that concentration can be broken through the dnd5e character sheet, use effect-ui-break-concentration:

{
  "actorIdentifier": "Wave B QA Caster",
  "effectIdentifier": "ActiveEffectId"
}
npm run fvtt:cdp -- --port 9230 --target-url http://127.0.0.1:30000 effect-ui-break-concentration --json '@break-concentration.json'

These commands are local QA primitives only; they are not part of Turn Protocol and do not replace player or DM decisions.