Get started

Two commands turn a folder into a BlockML project. init scaffolds the Node.js package, the Library and the agent files. Then install and validate.

1. Initialize with a package FQN

   Run this in an empty folder to create a Node.js project with package.json and dependencies. If the folder already has a package.json, it is updated in place. The FQN becomes a BML Library — for example com.acme.test — including README.bml. The Library is linked from package.json. AGENTS.md and CLAUDE.md are written automatically.

   terminal npx Copy

   npx @blockml/cli init com.acme.test

   • package.json Created if missing, otherwise merged — Core, CLI and the Library pointer
   • blocks/com/acme/test/Library.bml Project Library for the FQN
   • blocks/com/acme/test/README.bml Reading entry for the Library
   • AGENTS.md Cursor and other agents
   • CLAUDE.md Claude Code

2. Install and validate

   Install the dependencies, then validate the Blocks that init created. After this, the folder is a complete BlockML project.

   terminal npm Copy

   npm install && npx blockml validate

3. Try an experiment Optional

   Continue from this project through a use case. Init is already done. A coding agent takes the later steps. See Experiments