Home
Guides

CLI Reference

Every command, flag, and option accepted by the declarative-hex-worlds CLI binary.

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

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.

Warning: 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.

JSON flag schemas and error contracts

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

  • --pieceSourceRoots — { "sourceRoots": { "&lt;packName&gt;": "&lt;absoluteOrRelativePath&gt;" } }. 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": { "&lt;pieceId&gt;": { "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.

Built withSourcey
Edit this pageMIT LicenseKayKit assets