CLI

The dh command-line tool compiles, validates, and watches your pallets. For workspace configuration, see Workspace.

Commands

Command	Description
dh	Launch interactive mode (default if no command given)
dh interactive	Launch interactive mode (explicit)
dh build	Compile all pallets
dh watch	Watch for changes and auto-compile
dh validate	Validate pallets without writing output
dh clean	Clear the .dh/ cache directory
dh init	Initialize a new workspace
dh info <file>	Show metadata from a compiled .pallet file
dh help	Show available commands

Interactive Mode

Running dh with no arguments (or dh interactive) launches an interactive menu where you can choose what to do: build, watch, validate, clean, and more. This is the recommended way to use the CLI for day-to-day work.

Flags

Flag	Short	Works with	Description
--verbose	-v	build, watch, validate, clean	Show detailed output (Blender logs, file-level progress)
--clean	-c	build, watch	Clear cache before building

Example:

dh build --verbose --clean

Watch Mode

dh watch monitors your Source/ directory and recompiles when files change.

Debounce: waits for changes to settle before compiling (default: 1000ms, configurable via watchDebounceMs).

Manual controls:

Key	Action
Space, Enter, R, C	Trigger manual compile
Q, Ctrl+C	Exit watch mode

Inspecting Pallets

dh info displays metadata embedded in compiled .pallet files:

dh info Pallets/io.mltn.avatars.mltn-mayu.pallet

Output:

io.mltn.avatars.mltn-mayu.pallet
╭──────────────────┬─────────────────────────────────────╮
│ Property         │ Value                               │
├──────────────────┼─────────────────────────────────────┤
│ ID               │ io.mltn.avatars.mltn-mayu            │
│ Name             │ mltn Mayu                           │
│ Version          │ 0.0.1                               │
│ Author           │ mltn                                │
│ Built            │ 2026-02-05 10:30:00 -08:00          │
│ DH Version       │ 0.1.0                               │
│ Files            │ 42                                  │
│ Size             │ 2.4 MB                              │
│ Uncompressed     │ 3.1 MB                              │
│ Dependencies     │ tech.azuki.avatars.mayu ^3.0.0      │
│ Tags             │ avatar, character                   │
╰──────────────────┴─────────────────────────────────────╯

If no file is specified, dh info shows info for all pallets in the build directory.

Build Output

Success

Building io.mltn.avatars.mltn-mayu...
  ✓ Parsing definitions
  ✓ Validating references
  ✓ Processing textures
  ✓ Converting models
  ✓ Bundling assets
  ✓ Writing output

Build succeeded in 1.2s

Failure

Building io.mltn.avatars.mltn-mayu...
  ✓ Parsing definitions
  ✗ Validating references

Error in io.mltn.avatars.mltn-mayu/avatar.dh-avatar:12:5
  Missing required property 'name' in material definition

    10 |   "materials": {
    11 |     "body": {
  > 12 |       "diffuseTexture": "textures/body.png"
       |       ^
    13 |     }
    14 |   }

Build failed with 1 error

Build Pipeline

What dh build does under the hood:

1. Parse — Read all JSONC/.dh-* definition files
2. Validate — Check schemas, references, types, inheritance chains
3. Process textures — Channel packing, extraction, and resize from dh.texture definitions and @channel references
4. Convert models — FBX → GLB via Blender (cached by content hash)
5. Bundle — LZ4-compress assets into the output pallet
6. Output — Write compiled .pallet file to Pallets/