CLI Reference

import { Aside } from ‘@astrojs/starlight/components’;

This page is autogenerated from `src/cli/cli.ts` by `scripts/generate-cli-reference.ts`. Edits land in the source, not here.

The library ships a Node CLI binary named declarative-hex-worlds. Invoke via pnpm exec declarative-hex-worlds <command> or npx declarative-hex-worlds <command>.

Bootstrap first

Most commands operate against a local FREE or EXTRA pack tree. Before any tile / asset command, run:

pnpm exec declarative-hex-worlds bootstrap

This downloads the KayKit FREE pack and mirrors it flat under ./models/ (default). See the bootstrap guide for source modes, integrity verification, and customizing the output directory.

Full usage

declarative-hex-worlds <command> [options]

Commands:
  doctor    Report local source and docs status
  validate    Validate local FREE or EXTRA source counts
  manifest    Generate a manifest JSON from a source folder
  validate-manifest    Validate a generated manifest JSON and optionally write a normalized copy
  analyze    Analyze tile bounds, grid scale, row spacing, and warnings
  declarations    Emit tile declarations from a source folder, manifest, or registry
  guide-permutations    Emit guide-labeled road, river, crossing, and coast permutation metadata
  guide-scenarios    Emit extracted guide-page scenario metadata and validate page assets
  guide-usages    Emit renderer-ready page-level guide asset occurrence metadata
  guide-render-requests    Emit URL-resolved guide render request queues and optional page groups
  guide-apis    Emit public API to guide-page and asset coverage metadata
  guide-assets    Emit asset id to guide-page, API, docs, and visual coverage metadata
  guide-roles    Emit public role to guide-page, asset, and API coverage metadata
  coverage    Emit release-readiness coverage JSON or Markdown
  blueprint    Compile high-level 2.5D board intent to a recipe, plan, scenario, and diagnostics
  summarize-plan    Summarize terrain, placement, feature, asset, and local-only usage in a plan, recipe, scenario, or blueprint
  summarize-scenario    Summarize board, actor, spawn, patrol, quest, and local-only usage in a scenario
  pieces    Validate piece declarations and optionally emit seeded piece fill rules
  place-piece    Inspect and append one declared piece against a saved GameboardPlan, recipe, or scenario
  validate-plan    Validate a GameboardPlan JSON with optional registry rules
  analyze-layout    Analyze seeded layout fill rules against a saved GameboardPlan, recipe, or scenario
  spawn-groups    Plan separated spawn groups and route diagnostics against a plan, recipe, or scenario
  patrol-routes    Plan NPC/enemy patrol waypoints and segment diagnostics against a plan, recipe, or scenario
  patrol-script    Create executable simulation command steps from planned patrol routes and actor assignments
  validate-recipe    Validate a GameboardRecipe JSON and optionally compile it to a plan
  validate-scenario    Validate a GameboardScenario JSON and optionally compile its plan
  validate-simulation    Validate a GameboardScenario simulation script without executing it
  snapshot    Emit a neutral ECS interop snapshot from a plan, recipe, or scenario
  simulate-scenario    Run a GameboardScenario simulation script and emit event records, final plan, or ECS interop
  compatibility    Analyze one external GLB/GLTF for hex-tile compatibility and placement suggestions
  piece    Emit a custom piece declaration from an external GLB/GLTF compatibility scan
  pieces-from-assets    Scan GLB/GLTF files and emit custom piece declarations plus compatibility summaries
  bind    Scan an assets directory and emit a Zod-validated AssetSourceSpec JSON (the agent path — no prompts)
  init    Interactively bind an assets directory to an AssetSourceSpec (the human path — a TTY wizard)
  web    Bind an assets directory via a local web form (the visual path — a loopback config UI)
  extract    Copy GLTF assets and write a manifest to an output folder (alias: ingest)
  bootstrap    Materialize KayKit GLTF assets under a consumer asset root (PRD RB)

Run `declarative-hex-worlds <command> --help` for that command's full flag reference.

Global options (accepted by every command):
  --source <path>
      Override the source root every command resolves against (default: ./references/KayKit_Medieval_Hexagon_Pack_1.0_<FREE|EXTRA>, chosen by --edition).
  --edition free|extra
      Pack edition used to pick the default --source root and validate assets (default: free).

Options:
  --actorId <id>
  --allowExpectationFailures
  --allowInvalid
  --allowUnknownAssetIds <comma,separated,assetIds>
  --allowUnknownAssets
  --asset <path>
  --asset-root <path>
  --assetBaseUrl <url-or-path>
  --assetEdition free|extra|all
  --assetId <assetId>
  --assetId <comma,separated,ids>
  --assetIdPrefix <prefix>
  --assetIds <comma,separated,assetIds>
  --assetIds <comma,separated,ids>
  --assets <comma,separated,paths>
  --assetScope free|extra|all
  --assignments <path>
  --blueprint <path>
  --boardForwardEdge 0..5
  --categories <comma,separated,values>
  --category tiles|buildings|decoration|units
  --checksPassed
  --cols <n> --rows <n>
  --commit <sha>
  --config <path>
  --count <number>
  --coverage
  --creator <name>
  --defaultTerrain <terrain>
  --dir <path>
  --edition free|extra
  --editionScope free|extra|mixed|reference
  --emitRules
  --emitSourceUrls
  --excludeActors
  --excludePlacements
  --excludeQuests
  --excludeSpawnGroups
  --excludeTags <comma,separated,tags>
  --excludeTimeline
  --faction <faction>
  --failOnBlockedQuest
  --failOnWarning
  --fill <number>
  --force
  --format json
  --format markdown|json
  --freeOnly
  --generatedAt <iso-timestamp>
  --grouped
  --groups
  --groups <path>
  --guideRole <comma,separated,roles>
  --harbors <number>
  --height <number>
  --id <id>
  --idPrefix <prefix>
  --ids <comma,separated,pieceIds>
  --include-source-formats
  --includeAbsolutePaths
  --includeGroups
  --includeInterop
  --includePlan
  --includeRecipe
  --includeReport
  --includeReports
  --includeScenario
  --includeScenarioInspection
  --includeTreatments
  --intendedRole tile|prop|structure|unit
  --json
  --license <license>
  --manifest <path>
  --markdown
  --maxCount <number>
  --maxElevation <number>
  --minCount <number>
  --minimumEdition free|extra|all
  --mode per-piece|pool
  --modelForward +z|-z|+x|-x
  --name <name>
  --out <path>
  --outInterop <path>
  --outJson <path>
  --outManifest <path>
  --outMarkdown <path>
  --outPlan <path>
  --outRecipe <path>
  --outScenario <path>
  --outScenarioInspection <path>
  --overrides <path>
  --pack <id>
  --page <comma,separated,numbers>
  --pieceId <id>
  --pieceIdPrefix <prefix>
  --pieceOverrides <path>
  --pieces <path>
  --pieceSourceRoot <url-or-path>
  --pieceSourceRoots <json-path-or-inline-json>
  --plan <path>
  --port <n>
  --publicApi <comma,separated,api-names>
  --publicApi <comma,separated,names>
  --radius <number>
  --recipe <path>
  --registry <path>
  --requiresExtra
  --role <comma,separated,asset-treatment-roles>
  --role <comma,separated,roles>
  --role surface|building|unit|prop|tree|scatter|landmark|custom
  --roles <comma,separated,roles>
  --rounds <number>
  --routeId <id>
  --routes <path>
  --ruleIdPrefix <prefix>
  --rules <path>
  --scenario <comma,separated,ids>
  --scenario <path>
  --scenarioId <comma,separated,ids>
  --script <path>
  --seed <seed>
  --shape rectangle|hexagon
  --source github|zip
  --sourcePack <name>
  --sources <comma,separated,sources>
  --spawnCount <number>
  --spawnEdgePadding <number>
  --spawnMinDistance <number>
  --spawnSeed <seed>
  --tags <comma,separated,tags>
  --textureSet <texture-set>
  --topAssetLimit <number>
  --topAssets <number>
  --towns <number>
  --unencodedSourceUrls
  --verify
  --waterFill <number>
  --width <number>
  --width, --height, --radius, --seed, --faction, --textureSet, --defaultTerrain, --waterFill, --maxElevation, --towns, --harbors, --shape
  --zip <path>

Common command recipes

Doctor

Report local source + docs status. Useful first-time setup sanity check:

declarative-hex-worlds doctor

Validate a FREE pack

declarative-hex-worlds validate --edition free --source ./references/KayKit_Medieval_Hexagon_Pack_1.0_FREE

Compile a blueprint to a plan + scenario

declarative-hex-worlds blueprint \
  --blueprint ./blueprint.json \
  --outScenario ./scenario.json \
  --includeScenario

Run a simulation script

declarative-hex-worlds simulate-scenario \
  --scenario ./scenario.json \
  --script ./simulation.script.json \
  --rounds 10

Emit coverage ledger

declarative-hex-worlds coverage \
  --checksPassed \
  --outJson docs/release-readiness.json \
  --outMarkdown docs/release-readiness.md

Safe output paths

Every --out* flag goes through safeResolveOutput (PRD C1). Paths that escape the current working directory throw before any write happens. extract refuses to wipe a non-empty destination unless --force is passed.

Setting `HEX_WORLDS_OUT_ROOT` to an absolute path widens the output jail beyond the working directory. Use only in controlled CI environments. Never set it to `/` or any ancestor of sensitive paths — the CLI will write there without further restrictions.

JSON flag schemas and error contracts

Several flags accept JSON values directly or via a file path:

• --pieceSourceRoots — { "sourceRoots": { "<packName>": "<absoluteOrRelativePath>" } }. Keys must match [A-Za-z0-9_:-]+; any key that is a prototype-pollution vector (__proto__, constructor, prototype) is rejected before the object is parsed.
• --pieceOverrides — { "overrides": { "<pieceId>": { "footprint"?: ..., "criteria"?: ..., "tags"?: string[], "metadata"?: ... } } }.
• --pieces (all pieces* commands) — a path to a JSON file produced by pieces-from-assets. Not accepted as inline JSON.

All JSON parsing errors surface as GameboardCliError with a descriptive message on stderr. Exit code is always non-zero on error.

Errors

CLI errors are GameboardCliError instances (PRD D2). The library’s error taxonomy is documented in the errors reference.