Comprehensive List of arnis CLI Arguments and Args Struct Validation Rules

The Args struct in 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 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) 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) 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

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

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

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

# 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}