Skip to main content
Fabled
Fabled

Module Creator

Build your first Fabled module

Install the Module CLI, scaffold a valid package, and understand the files it creates.

Prerequisites

  • Node.js 20.20 or newer. The Fabled web repository itself currently requires ^20.20.0 or >=22.22.0.
  • A Fabled account. Publishing also requires an available Module CLI pairing service and an active publisher namespace.
  • Public bootstrap: @fabledgg/module-cli is available from npm under the bootstrap dist-tag while 0.1.0 remains reserved for the post-merge release.

Run the public bootstrap

Try the current public CLI directly from npm without installing it globally:

npx @fabledgg/module-cli@bootstrap module --help

The rest of this guide uses the installed-binary spelling fabled module. If you are contributing to the Fabled web repository itself, you can instead use npm run modules:cli -- module.

npx @fabledgg/module-cli@bootstrap module init my-dice \
  --publisher-id my-studio \
  --publisher-name \"My Studio\"

Choose an installation style

The recommended one-off form needs no global install:

npx @fabledgg/module-cli@bootstrap module --help

For a team project, install the bootstrap as a development dependency so package-lock.json records the resolved version and local and CI validation use the same contract build.

npm install --save-dev @fabledgg/module-cli@bootstrap
npx fabled module --help

A global install is optional. It exposes the same fabled binary, but a project-local pinned version is easier to reproduce and audit.

npm install --global @fabledgg/module-cli@bootstrap
fabled module --help

Scaffold a project

fabled module init my-dice \
  --publisher-id my-studio \
  --publisher-name "My Studio"

The directory must not already exist. The scaffold creates the Dice & Chat example with a canonical fabled.module.json, a reviewed dice action, a host-owned Dice Tray frame, and an English locale file. Change the local module slug with --module-id and the display name with --name.

my-dice/
├── fabled.module.json
├── actions/roll.json
├── frames/dice-tray.json
└── locales/en.json

Make the first check

fabled module validate my-dice
fabled module pack my-dice --output my-dice.zip
fabled module inspect my-dice.zip

A clean validation proves the package matches the local v1 contract. It does not approve, install, activate, or execute the module.