CLI reference

@kata-framework/cli ships a kata binary with three commands.

bun add -d @kata-framework/cli
bunx kata --help

`kata build <glob>`

Parse .kata files and write compiled .kson.json to an output directory.

kata build "scenes/**/*.kata" --out dist/kson

Output layout preserves source directory structure. scenes/intro/prologue.kata → dist/kson/scenes/intro/prologue.kson.json.

Same as build, but re-runs on file change. Useful in development alongside your UI dev server.

kata watch "scenes/**/*.kata"

Visualize scene connectivity. Two output formats, one analysis flag.

kata graph "scenes/**/*.kata" --format dot > graph.dot
kata graph "scenes/**/*.kata" --format json
kata graph "scenes/**/*.kata" --lint

Flag	Values	Purpose
`--format`	`dot` \| `json`	Output format (default `dot`)
`--lint`	—	Fail if there are orphan scenes or dead-end choices
`--root <id>`	—	Start reachability analysis from this scene id

--lint exits non-zero on problems, so you can gate CI on it:

- run: bunx kata graph "scenes/**/*.kata" --lint

dot output pipes into Graphviz:

kata graph "scenes/**/*.kata" --format dot | dot -Tsvg > scenes.svg

Resolved from CWD. CLI flags take precedence.

{
  "glob": "scenes/**/*.kata",
  "out": "dist/kson",
  "pretty": false,
  "root": "intro"
}