# Comprehensive List of arnis CLI Arguments and Args Struct Validation Rules

> Explore the comprehensive arnis CLI arguments defined in Args struct. Understand Java/Bedrock directory validation, spawn point checks, and more for robust configuration with louis-e/arnis.

- Repository: [Louis Erbkamm/arnis](https://github.com/louis-e/arnis)
- Tags: api-reference
- Published: 2026-03-20

---

**The `Args` struct in [`src/args.rs`](https://github.com/louis-e/arnis/blob/main/src/args.rs) defines over 20 command-line options using `clap` derive macros, with the `validate_args` function enforcing runtime constraints such as Java Edition directory requirements, Bedrock Edition optional paths, and spawn point containment within bounding boxes.**

The **arnis** open-source project generates Minecraft worlds from real-world geographic data. Understanding the **CLI arguments and validation rules in the Args struct** is critical for configuring world generation correctly across Java and Bedrock editions. This guide examines the complete argument specification in [`src/args.rs`](https://github.com/louis-e/arnis/blob/main/src/args.rs) and the post-parse validation logic that ensures runtime consistency.

## Args Struct Overview

The `Args` struct resides in **[[`src/args.rs`](https://github.com/louis-e/arnis/blob/main/src/args.rs)](https://github.com/louis-e/arnis/blob/main/src/args.rs)** and serves as the single source of truth for CLI configuration. It uses **clap** derive macros for declarative parsing, while the `validate_args` function (lines 86-140) implements additional runtime checks beyond what `clap` can enforce during parsing.

## Complete CLI Arguments Reference

### Bounding Box and Location Input

These arguments define the geographic area for world generation:

- **`--bbox`** (required): A comma-separated bounding box string (lat1,lng1,lat2,lng2) parsed via `LLBBox::from_str`. Defined at lines 10-13 with `#[arg(long, allow_hyphen_values = true, value_parser = LLBBox::from_str)]`.
- **`--file`**: Optional path to an input file for offline processing. Belongs to the `"location"` group, making it mutually exclusive with `--save-json-file` (lines 14-17).
- **`--save-json-file`**: Optional path to save raw JSON data. Mutually exclusive with `--file` via the `"location"` group (lines 18-21).

### Output Configuration

These arguments control world save locations and edition targeting:

- **`--output-dir`** (alias `--path`): Optional `PathBuf` specifying the output directory. Defined at lines 22-26 with `#[arg(long = "output-dir", alias = "path")]`.
- **`--bedrock`**: Boolean flag (default `false`) that switches from Java Edition to Bedrock Edition output format (lines 27-30).

### Data Source and Scaling Options

- **`--downloader`**: Backend selector for OSM data retrieval (default `"requests"`). Lines 31-34.
- **`--scale`**: Floating-point scale factor for world dimensions (default `1.0`). Lines 35-38.
- **`--ground-level`**: Integer Y-coordinate for ground level (default `-62`). Lines 39-42.

### Feature Generation Toggles

These boolean flags control which world elements are generated:

- **`--terrain`**: Enable terrain generation (default `false`). Lines 43-46.
- **`--interior`**: Enable interior generation (default `true`). Uses `ArgAction::Set` with `default_missing_value = "true"` to support `--interior` or `--interior=false` syntax. Lines 47-50.
- **`--roof`**: Enable roof generation (default `true`). Same toggle pattern as `--interior`. Lines 51-54.
- **`--fillground`**: Fill ground below structures (default `false`). Lines 55-58.
- **`--city-boundaries`**: Respect administrative city boundaries (default `true`). Lines 59-64.

### Debugging and Advanced Options

- **`--debug`**: Enable verbose debug output (default `false`). Lines 65-68.
- **`--timeout`**: Network timeout duration parsed via `parse_duration` (expects integer seconds). Lines 69-71.

### Spawn Point Configuration

- **`--spawn-lat`**: Optional spawn latitude allowing negative values (lines 73-76).
- **`--spawn-lng`**: Optional spawn longitude allowing negative values (lines 77-80).

Both arguments use `allow_hyphen_values = true` to correctly parse negative coordinates.

## Validation Rules in validate_args

The `validate_args` function (lines 86-140 in [`src/args.rs`](https://github.com/louis-e/arnis/blob/main/src/args.rs)) enforces runtime constraints that `clap` cannot handle during initial parsing.

### Output Directory Validation

The function distinguishes between Java and Bedrock editions:

**Java Edition** (`--bedrock` not set):
- `--output-dir` is **mandatory**.
- The path must exist and be a directory.

**Bedrock Edition** (`--bedrock` set):
- `--output-dir` is **optional**.
- If provided, the path must exist and be a directory.

Error messages include:

```

Path does not exist: /path/to/dir
Path is not a directory: /path/to/file
The --output-dir argument is required for Java Edition ...

```

### Spawn Point Validation

When `--spawn-lat` and `--spawn-lng` are used, three checks apply:

1. **Pair requirement**: Both coordinates must be provided together. Providing only one returns:
   ```

   Both --spawn-lat and --spawn-lng must be provided together.
   ```

2. **Coordinate validity**: Values must form a valid `LLPoint` via `LLPoint::new`, which validates latitude (-90 to 90) and longitude (-180 to 180) ranges.

3. **Bounding box containment**: The spawn point must lie inside the `--bbox` area using `args.bbox.contains(&llpoint)`. If outside:
   ```

   Spawn point (--spawn-lat, --spawn-lng) must be within the bounding box.
   ```

### Mutual Exclusivity Rules

The `--file` and `--save-json-file` arguments are mutually exclusive via `clap`'s group validation (`group = "location"`). This is enforced during parsing before `validate_args` runs.

## Practical Usage Examples

### Java Edition with Required Output Directory

```bash
arnis \
  --output-dir /home/user/.minecraft/saves/paris \
  --bbox 48.8566,2.3522,48.8580,2.3540 \
  --scale 2.0 \
  --ground-level -60 \
  --terrain \
  --debug

```

If `/home/user/.minecraft/saves/paris` does not exist, `validate_args` returns:

```

Path does not exist: /home/user/.minecraft/saves/paris

```

### Bedrock Edition Without Output Directory

```bash
arnis \
  --bedrock \
  --bbox -33.8688,151.2093,-33.8660,151.2120 \
  --city-boundaries=false \
  --interior=false

```

In Bedrock mode, the output directory is optional, but if provided, it must still exist and be a valid directory.

### Custom Spawn Point Within Bounding Box

```bash
arnis \
  --output-dir ./world \
  --bbox 10.0,20.0,15.0,25.0 \
  --spawn-lat 12.0 \
  --spawn-lng 22.0

```

The validation ensures (12.0, 22.0) falls within the bbox (10.0,20.0) to (15.0,25.0). If you only provide `--spawn-lat` without `--spawn-lng`, the validator returns:

```

Both --spawn-lat and --spawn-lng must be provided together.

```

### Overriding Default Boolean Flags

```bash

# Disable interior generation explicitly

arnis --output-dir ./world --bbox 0,0,1,1 --interior=false

# Enable interior (same as default behavior)

arnis --output-dir ./world --bbox 0,0,1,1 --interior

# Disable city boundaries

arnis --output-dir ./world --bbox 0,0,1,1 --city-boundaries=false

```

## Summary

- The `Args` struct in [`src/args.rs`](https://github.com/louis-e/arnis/blob/main/src/args.rs) defines over 20 CLI options using `clap` derive macros, organized into location input, output configuration, scaling, feature toggles, and spawn coordinates.
- **Validation rules** in `validate_args` enforce Java Edition directory requirements (mandatory output path), Bedrock Edition optional paths, and spawn point consistency (paired arguments, valid coordinates, containment within bounding box).
- Boolean flags like `--interior`, `--roof`, and `--city-boundaries` default to `true` but support explicit negation via `--flag=false` syntax using `clap`'s `ArgAction::Set`.
- The `--file` and `--save-json-file` options are mutually exclusive through `clap` group validation, while `--bbox` remains the only universally required argument across all execution modes.

## Frequently Asked Questions

### What is the only required CLI argument for arnis?

The `--bbox` argument is mandatory for all execution modes. It accepts a comma-separated string of four coordinates (latitude1,longitude1,latitude2,longitude2) parsed via `LLBBox::from_str`. Unlike `--output-dir`, which is only required for Java Edition, the bounding box defines the geographic scope of world generation and must always be provided.

### Why does arnis require an output directory for Java Edition but not Bedrock?

Java Edition worlds must be written directly to an existing Minecraft saves directory structure, so `validate_args` enforces that `--output-dir` is present and points to an existing directory when `--bedrock` is not set. For Bedrock Edition, the tool can generate world data without a pre-existing directory path, making the argument optional—though if provided, it still undergoes existence and directory validation.

### How do I set a custom spawn point in arnis?

Use the `--spawn-lat` and `--spawn-lng` arguments together to specify decimal coordinates. The validation logic requires both values to be present, checks that they form a valid `LLPoint` (valid latitude/longitude ranges), and verifies that the point falls within the bounding box defined by `--bbox` using the `contains` method. If the point lies outside the bbox, the validator returns a specific error requiring the spawn to be within bounds.

### Can I disable specific world generation features like interiors or roofs?

Yes. The `--interior`, `--roof`, and `--city-boundaries` flags default to `true` but support explicit negation using `--flag=false` syntax (e.g., `--interior=false`). This is implemented via `clap`'s `ArgAction::Set` with `default_missing_value = "true"`, allowing the flags to function as toggles that can be explicitly disabled when needed while defaulting to enabled when the flag is omitted.