---
layout: page
title: CLI Reference
permalink: /docs/cli-reference/
---

# CLI Reference

The MDL command-line interface provides tools for creating, validating, and building **simplified** datapacks.

## Overview

```bash
mdl [command] [options]
```

## Commands

### `new` - Create a new datapack project

Creates a new datapack project with the specified structure.

```bash
mdl new <project_name> [options]
```

**Options:**
- `--name "Pack Name"` - Set the datapack name
- `--pack-format N` - Set the pack format (default: 82)
- `--format {legacy,modern}` - Pack format style: 'legacy' (pre-82) or 'modern' (82+) (default: modern)
- `--description "Description"` - Set the datapack description

**Examples:**

**Modern format (default):**
```bash
mdl new my_pack --name "My Adventure Pack"
# Creates pack format 82+ with simplified syntax
```

**Legacy format:**
```bash
mdl new my_pack --name "My Adventure Pack" --format legacy --pack-format 48
# Creates legacy pack format 48
```

This creates:
```
my_pack/
├── mypack.mdl
└── README.md
```

The generated `mypack.mdl` file will contain **simplified** syntax:

```mdl
// mypack.mdl - Generated by mdl new
pack "My Adventure Pack" description "A simplified datapack" pack_format 82;

namespace "example";

// Number variables only
var num counter = 0;
var num health = 20;

function "hello" {
    say Hello, Minecraft!;
    tellraw @a {"text":"Welcome to my simplified datapack!","color":"green"};
    
    // Variable substitution
    say Counter: $counter$;
    say Health: $health$;
    
    // Control structures
    if "$health$ < 10" {
        say Health is low!;
        health = health + 5;
    }
    
    while "$counter$ < 5" {
        say Counter: $counter$;
        counter = counter + 1;
    }
    
    for player in @a {
        say Hello $player$;
        effect give @s minecraft:speed 5 0;
    }
}

// Lifecycle hooks
on_load "example:hello";
on_tick "example:hello";
```

### `check` - Validate MDL files

Validates MDL files for syntax errors and issues.

```bash
mdl check <path> [options]
```

**Arguments:**
- `<path>` - Path to `.mdl` file, directory, or space-separated file list

**Options:**
- `--json` - Output results in JSON format for detailed diagnostics

**Examples:**
```bash
# Check a single file
mdl check my_pack.mdl

# Check an entire directory
mdl check my_pack/

# Check multiple specific files
mdl check "file1.mdl file2.mdl file3.mdl"

# Get detailed JSON output
mdl check --json my_pack/
```

**Output:**
- Success: No output (exit code 0)
- Errors: Error messages with file paths and line numbers (exit code 1)

### `build` - Build datapacks

Compiles MDL files into Minecraft datapacks.

```bash
mdl build [options]
```

**Required Options:**
- `--mdl <path>` or `--src <path>` - Path to `.mdl` file, directory, or space-separated file list
- `-o, --out <dir>` - Output directory for the built datapack

**Optional Options:**
- `--wrapper <name>` - Custom wrapper folder/zip name (default: first namespace or pack name slug)
- `--pack-format <N>` - Minecraft pack format (default: 82 for modern syntax)
- `-v, --verbose` - Show detailed processing information including file merging
- `--py-module <path>` - Alternative: build from Python module with `create_pack()` function

**Examples:**

**Build a single file:**
```bash
mdl build --mdl my_pack.mdl -o dist
```

**Build from directory:**
```bash
mdl build --mdl my_pack/ -o dist
```

**Build multiple specific files:**
```bash
mdl build --mdl "core.mdl combat.mdl ui.mdl" -o dist
```

**Build with custom wrapper name:**
```bash
mdl build --mdl my_pack.mdl -o dist --wrapper adventure_pack
```

**Build with verbose output:**
```bash
mdl build --mdl my_pack/ -o dist --verbose
```

### `check-advanced` - Advanced validation

Performs advanced validation of generated `.mcfunction` files.

```bash
mdl check-advanced <path> [options]
```

**Arguments:**
- `<path>` - Path to `.mdl` file, directory, or space-separated file list

**Examples:**
```bash
# Validate generated mcfunction files
mdl check-advanced my_pack.mdl

# Validate entire project
mdl check-advanced my_pack/
```

## **Simplified** MDL Examples

### Basic **Simplified** Datapack

```mdl
// simple_pack.mdl
pack "Simple Pack" description "A simplified example" pack_format 82;

namespace "example";

// Number variables only
var num counter = 0;
var num health = 20;
var num level = 1;

function "init" {
    say Initializing...;
    counter = 0;
    health = 20;
    level = 1;
}

function "tick" {
    counter = counter + 1;
    
    // Variable substitution
    say Counter: $counter$;
    say Health: $health$;
    say Level: $level$;
    
    // Control structures
    if "$health$ < 10" {
        say Health is low!;
        health = health + 5;
        effect give @s minecraft:regeneration 10 1;
    }
    
    while "$counter$ < 5" {
        say Counter: $counter$;
        counter = counter + 1;
    }
    
    for player in @a {
        say Hello $player$;
        effect give @s minecraft:speed 5 0;
    }
}

// Lifecycle hooks
on_load "example:init";
on_tick "example:tick";
```

**Build and use:**
```bash
mdl build --mdl simple_pack.mdl -o dist
# Copy dist/simple_pack/ to your world's datapacks folder
# Run /reload in-game
```

### Multi-Namespace **Simplified** Project

```mdl
// core.mdl
pack "Multi-Namespace Pack" description "Simplified multi-namespace example" pack_format 82;

namespace "core";

// Core variables
var num system_version = 1;
var num player_count = 0;

function "init" {
    say [core:init] Initializing system...;
    system_version = 1;
    player_count = 0;
}

function "tick" {
    say [core:tick] Core systems running...;
    player_count = 0;
    for player in @a {
        player_count = player_count + 1;
    }
    say Player count: $player_count$;
}

namespace "combat";

// Combat variables
var num weapon_damage = 10;

function "weapon_effects" {
    say [combat:weapon_effects] Applying weapon effects...;
    execute as @a[nbt={SelectedItem:{id:'minecraft:diamond_sword'}}] run effect give @s minecraft:strength 1 0 true;
    weapon_damage = weapon_damage + 2;
    say Weapon damage: $weapon_damage$;
}

// Hooks
on_load "core:init";
on_tick "core:tick";
on_tick "combat:weapon_effects";
```

**Build multi-namespace project:**
```bash
mdl build --mdl core.mdl -o dist --verbose
```

## **Simplified** Language Features

The **simplified** MDL language focuses on:

### Number Variables Only
```mdl
var num counter = 0;
var num health = 20;
var num level = 1;
```

### Variable Substitution
```mdl
// In strings
say Health: $health$;
tellraw @a {"text":"Level: $level$","color":"gold"};

// In conditions
if "$health$ < 10" {
    say Health is low!;
}

while "$counter$ > 0" {
    say Counter: $counter$;
    counter = counter - 1;
}
```

### Control Structures
```mdl
// If/else if/else
if "$health$ < 10" {
    say Health is low!;
} else if "$level$ > 5" {
    say High level player!;
} else {
    say Normal player;
}

// While loops
while "$counter$ > 0" {
    say Counter: $counter$;
    counter = counter - 1;
}

// For loops
for player in @a {
    say Hello $player$;
    effect give @s minecraft:speed 5 0;
}
```

## Common Workflows

### Development Workflow

1. **Create a new project:**
   ```bash
   mdl new my_pack --name "My Pack"
   ```

2. **Edit the generated file** with **simplified** syntax

3. **Check for errors:**
   ```bash
   mdl check my_pack/mypack.mdl
   ```

4. **Build the datapack:**
   ```bash
   mdl build --mdl my_pack/mypack.mdl -o dist
   ```

5. **Test in Minecraft:**
   - Copy `dist/my_pack/` to your world's datapacks folder
   - Run `/reload` in-game

### Multi-file Development

1. **Create the main file:**
   ```bash
   mdl new my_pack --name "My Pack"
   ```

2. **Create additional module files** (without pack declarations)

3. **Build the entire project:**
   ```bash
   mdl build --mdl my_pack/ -o dist --verbose
   ```

### Testing and Validation

1. **Check syntax:**
   ```bash
   mdl check my_pack/
   ```

2. **Build with verbose output:**
   ```bash
   mdl build --mdl my_pack/ -o dist --verbose
   ```

3. **Advanced validation:**
   ```bash
   mdl check-advanced my_pack/
   ```

## Error Handling

### Common Errors

1. **Missing pack declaration**: Single files must have a pack declaration
2. **Duplicate pack declarations**: Only the first file in a multi-file project should have a pack declaration
3. **Function conflicts**: Duplicate function names within the same namespace will cause an error
4. **Invalid variable types**: Only `var num` is supported in the simplified language
5. **Missing semicolons**: All statements must end with semicolons `;`

### Debugging

Use the `--verbose` flag for detailed output:
```bash
mdl build --mdl my_pack.mdl -o dist --verbose
```

Use JSON output for detailed diagnostics:
```bash
mdl check --json my_pack.mdl
```

## **Simplified** Language Benefits

The **simplified** MDL language provides:

1. **Reliability**: Control structures that actually work
2. **Simplicity**: Number variables only with `$variable$` substitution
3. **Clarity**: Clear, readable syntax with explicit block boundaries
4. **Performance**: Efficient compilation to Minecraft commands
5. **Maintainability**: Easy to understand and modify

This **simplified** approach makes it much easier to create reliable Minecraft datapacks without the complexity of the previous version.
