CLI tools

The BlockML CLI is the toolchain for scaffolding, exploring, checking and compiling Blocks. Bootstrap a repo with npx @blockml/cli init, then invoke npx blockml from the project. BML stays the source of truth — companions such as TypeScript, HTML or XSD are derived.

terminal npx

npx blockml --help

Every command

These are the tools printed by npx blockml --help. Run npx blockml <command> --help for flags, defaults and constraints.

init Scaffold a project

search Where something is

scan Which packages or types match

inspect The Block already resolved

graph How it connects

new Create a Block .bml

validate Parser + semantic check

compile Render a target

transform Run a ModelTransformation

Everyday workflow

Discover the model with the CLI first. Generic grep, find and file reads remain allowed — they are not the first way in.

search / scan Find FQNs
inspect Read the resolved Block
graph See structure if needed
edit BML Smallest change
validate Check the model
compile Update companions

Start

Turn a folder into a project

Bootstrap a new repo with npx @blockml/cli init. Afterward use npx blockml. Empty folders get a Node.js package; existing package.json files are merged.

init Scaffold a BlockML project

Writes a project Library and README for the package FQN, points package.json at that Library, and creates AGENTS.md and CLAUDE.md. Empty folders get package.json with @blockml/core and @blockml/cli. Existing package.json files are updated in place. Does not overwrite existing files. Does not run npm install unless --install is passed.
usage init
```
npx @blockml/cli init <package-fqn> [--src dir] [--install]
```
New or existing folder example
```
npx @blockml/cli init com.acme.test
```
Install immediately example
```
npx @blockml/cli init com.acme.test --install
```
Then validate example
```
npm install && npx blockml validate
```

Discover

Find your way in the model

Use these four before opening files. The corpus is the same as validate --all.

search Find FQNs

Full-text search over the model. Use this when you know words but not the FQN. A missing or stale .blockml/search/ index is rebuilt automatically.
usage search
```
npx blockml search <query> [--json] [--limit n]
```
Find by words example
```
npx blockml search lamp brightness
```
Rebuild the index example
```
npx blockml search index --force
```
scan List packages or types

Match PackageSelector or TypeSelector tokens. Not full-text search — no score and no index. Quote tokens that contain * or ** so the shell does not expand them. Multiple selectors are OR.
usage scan
```
npx blockml scan package|type <selector>…
```
Exact type example
```
npx blockml scan type org.blockml.bml.core.Block
```
Types in a package and below example
```
npx blockml scan type 'org.blockml.bml.core.**'
```
Direct child packages example
```
npx blockml scan package 'org.blockml.bml.*' --json
```
inspect Resolved Block JSON

When you already know the FQN, inspect returns compact JSON of the live Block — effective members included. Output is not a write format; do not round-trip it back to BML. Default depth is 1, cap is 3.
usage inspect
```
npx blockml inspect <fqn> [--depth n]
```
Inspect a type example
```
npx blockml inspect org.blockml.bml.core.Block
```
One extra hop example
```
npx blockml inspect org.blockml.bml.core.Block --depth 2
```
graph Inheritance, uses, paths

Ask how Blocks connect. Prefer named operations over Cypher. Rebuild with graph index if the index is missing or stale. path follows outgoing authored edges; reverse questions use used-by.
usage graph
```
npx blockml graph uses|used-by|neighbors|ancestors|descendants|members <fqn>
```
What this type uses example
```
npx blockml graph uses org.blockml.bml.core.Block
```
What uses this type example
```
npx blockml graph used-by org.blockml.bml.core.Block
```
Rebuild the graph example
```
npx blockml graph index --force
```

Change

Create, check, compile

Edit BML first. Then validate. Then compile or update companions to match. Do not patch generated output to fix the model.

new Create a Block

Writes a .bml file and exports it from the owning Library. Default baseType is org.blockml.bml.core.Block. Does not overwrite an existing file. Prefer existing Blocks over new duplicates.
usage new
```
npx blockml new <fqn> [--baseType FQN] [--is text]
```
Create a type example
```
npx blockml new com.example.bml.Lamp --is "A lamp with a brightness"
```
Set the base type example
```
npx blockml new com.example.bml.Lamp --baseType org.blockml.bml.core.Block
```
validate Parser + semantic check

Ordinary project work after edits. Default: project sources only, not npm. --all checks the entire reachable corpus, including npm — do not use it as the default after every edit. Validity is parse plus semantic validate; XSD is a compile target, not a checker.
usage validate
```
npx blockml validate [--all] [<file>]
```
Project sources example
```
npx blockml validate
```
One file example
```
npx blockml validate blocks/com/example/bml/Lamp.bml
```
Entire corpus example
```
npx blockml validate --all
```
compile Render derived output

When a companion is a compile target, change BML first, then recompile. Built-in targets: blockdoc, xsd, fatblock. Custom targets come from targetPackages.
usage compile
```
npx blockml compile blockdoc|xsd|fatblock [--out dir]
```
Blockdoc example
```
npx blockml compile blockdoc
```
XSD schemas example
```
npx blockml compile xsd
```
FatBlock per package example
```
npx blockml compile fatblock --per-package
```
transform Run a ModelTransformation

Parent command; V1 defines apply only. The execution FQN is a pending one-shot, an available template, or a template outside _meta.transform. Only one transform may run at a time in the same Git worktree, and the worktree must be clean.
usage transform
```
npx blockml transform apply <execution-fqn> [--library path]
```
Apply an execution example
```
npx blockml transform apply com.example.bml._meta.transform.RenameType
```
Target Library.bml example
```
npx blockml transform apply com.example.bml._meta.transform.RenameType --library ./blocks/com/example/bml/Library.bml
```

Shared flags

Most commands accept the same corpus and output flags. Exit 0 on success, 1 on diagnostic errors, 2 on usage or configuration errors.

--src dir Source directory override
--libraries a,b Extra Library.bml seeds
--json Machine-readable output
--help / -h Command help

Start with init

Run npx @blockml/cli init with a package FQN, then npm install && npx blockml validate. After that, npx blockml is the everyday CLI.

Get Started Documentation