Complete command reference for the z3ed CLI tool, including all automation and AI-powered features.

ROM Operations

`z3ed rom read`

Read bytes from ROM at specified address.

Syntax:

z3ed rom read --address <hex> [--length <bytes>] [--data-format <hex|ascii|both>] [--format json|text]

Notes:

--data-format controls the hex/ascii view of bytes.
--format controls the output structure (json/text).

Examples:

# Read 16 bytes from address 0x1000
z3ed rom read --address 0x1000 --length 16
 
# Read 256 bytes and display as ASCII
z3ed rom read --address 0x20000 --length 256 --data-format ascii
 
# Read single byte
z3ed rom read --address 0xFFFF

Output:

{
  "address": "0x001000",
  "data": "A9 00 85 2C A9 01 85 2D A9 02 85 2E A9 03 85 2F",
  "ascii": ".........,......",
  "length": 16,
  "format": "both"
}

`z3ed rom write`

Write bytes to ROM at specified address.

Syntax:

z3ed rom write --address <hex> --data <hex_string> [--sandbox]

Notes:

--sandbox writes to a sandbox copy instead of the original ROM.

Examples:

# Write 4 bytes
z3ed rom write --address 0x1000 --data "A9 00 85 2C"
 
# Write to a sandboxed ROM copy (safe default for edits)
z3ed rom write --address 0x2000 --data "FF FE FD FC" --sandbox

`z3ed rom info`

Show basic ROM metadata.

Syntax:

z3ed rom info --rom <file>

Examples:

z3ed rom info --rom zelda3.sfc

`z3ed rom diff`

Compare two ROM files.

Syntax:

z3ed rom diff --rom_a <file> --rom_b <file>

Examples:

z3ed rom diff --rom_a base.sfc --rom_b mod.sfc

`z3ed rom compare`

Compare a ROM against a baseline to identify differences.

Syntax:

z3ed rom compare --rom <file> --baseline <file>

Examples:

z3ed rom compare --rom mod.sfc --baseline vanilla.sfc

`z3ed rom validate`

Validate ROM integrity and structure.

Syntax:

z3ed rom validate

Examples:

# Full validation

z3ed rom validate

Output:

{
  "validation_passed": true,
  "results": "checksum: PASSED; header: PASSED"
}

`z3ed rom generate-golden`

Generate a golden ROM file for testing.

Syntax:

z3ed rom-generate-golden --rom_file <file> --golden_file <file>

Examples:

z3ed rom-generate-golden --rom_file zelda3.sfc --golden_file golden.sfc

Editing Commands

These commands operate directly on ROM data (no GUI required).

Dungeon Commands

dungeon-describe-room --room <hex> [--include-objects]
dungeon-list-sprites --room <hex>
dungeon-list-objects --room <hex>
dungeon-list-custom-collision --room <hex> [--tiles <hex,hex,...>] [--nonzero] [--all]
dungeon-export-custom-collision-json --out <path> [--room <hex> | --rooms <hex,hex,...> | --all] [--report <path>] [--sandbox]
dungeon-import-custom-collision-json --in <path> [--dry-run [--report <path>]] [--sandbox | --mock-rom] [--replace-all --force]
dungeon-export-water-fill-json --out <path> [--room <hex> | --rooms <hex,hex,...> | --all] [--report <path>] [--sandbox]
dungeon-import-water-fill-json --in <path> [--dry-run [--report <path>]] [--sandbox | --mock-rom] [--strict-masks]
dungeon-minecart-audit [--room <hex> | --rooms <hex,hex,...> | --all] [--only-issues]
dungeon-map --room <hex> [--layer <0|1|2>] *(overlays Oracle custom collision tiles when present)*
dungeon-list-chests --room <hex>
dungeon-get-entrance --entrance <hex> [--spawn]
entrance-info --entrance <hex> [--spawn]
dungeon-export-room --room <hex> --output <file>
dungeon-place-object --room <hex> --id <hex> --x <int> --y <int> [--size <int>] [--layer <0|1|2>] [--manifest <path>] [--write]
dungeon-get-room-tiles --room <hex> *(stubbed)*
dungeon-set-room-property --room <hex> --property <name> --value <value> [--manifest <path>]

dungeon-place-object is a dry-run unless --write is supplied. Both modes execute the same immutable capacity preflight. In-place edits can proceed without a manifest, but a shared or growing object stream fails closed unless an explicit manifest defines dungeon_stream_regions.objects with the copy_on_write strategy and allocator-owned space. The manifest remains an ownership guard: protected current-stream, allocation, object-pointer, or door-pointer writes are rejected before either dry-run or write can mutate ROM bytes.

dungeon-set-room-property accepts layout/layout_id values 0-7 and floor1/floor2 values 0-15. These properties are persisted in the two-byte object-stream header with per-field read/modify/write; unrelated bits and the object payload remain unchanged. A shared stream requires the same manifest-backed copy_on_write capability described above. Successful non-mock writes require a completed destination backup before replacement.

The collision and water-fill JSON import commands validate without mutation when --dry-run is present. Without it, they immediately save the active ROM with a required backup. --sandbox redirects that save and backup to the sandbox copy; the source ROM and its directory remain unchanged. --mock-rom is an in-memory test mode and is rejected when combined with --sandbox. --report is accepted only with a non-sandbox --dry-run; write-mode and sandbox imports reject it before ROM or sandbox work. Report paths must not alias the active ROM, including through symlinks or hardlinks. Reports are staged in exclusive same-directory temporary files and published with rename/replace after a final path-identity check. Collision/water JSON exports use the same ROM-alias checks; when --out and --report are published together, a partial publication is rolled back before the command returns. Exports may use --sandbox; their explicit --out and --report artifacts must remain separate from both the sandbox ROM and its source ROM.

When --spawn is set, the ID must be 0x00-0x06. Both entrance commands report the dedicated spawn fields (quadrant, overworld_door_tilemap, and the linked regular entrance_id) and omit the regular-entrance-only door field.

Example:

z3ed dungeon-describe-room --room=0x05 --rom=zelda3.sfc

Add --include-objects for a read-only objects array in ROM-stream order. Each record reports hexadecimal object_id, subtype (1, 2, or 3), x, y, size, and zero-based stream_index. The reported object_count then equals the array length. Lightable torches and pushable blocks are omitted because they come from separate global tables rather than the encoded room object stream. Without the flag, the legacy output and count are unchanged.

Overworld Commands

overworld-describe-map --map <hex>
overworld-find-tile --tile <hex>
overworld-list-warps --map <hex>
overworld-list-sprites --map <hex>
overworld-list-items --map <hex>
overworld-get-entrance --entrance <hex>
overworld-tile-stats --map <hex>

Example:

z3ed overworld-describe-map --map=0x40 --rom=zelda3.sfc

GUI Automation (requires GUI gRPC server)

gui-place-tile --tile <hex> --x <x> --y <y>
gui-click (--target <path> | --widget-key <key>) [--click-type <left|right|middle|double>]
gui-type (--target <path> | --widget-key <key>) --text <text> [--clear-first]
gui-wait [--condition <condition>] [--widget-key <key>] [--timeout-ms <ms>] [--poll-interval-ms <ms>]
gui-assert [--condition <condition>] [--widget-key <key>]
gui-discover-tool [--window <name>] [--type <type>]
gui-summarize-widgets
gui-screenshot [--region <region>]

Testing Commands

`z3ed test-list`

List available tests.

`z3ed test-run`

Execute tests.

Syntax:

z3ed test-run [--label <label>] [--format json|text]

`z3ed test-status`

Check test execution status.

Resource & Search Commands

resource-list --type <type>
resource-search --query <text> [--type <type>]
message-list, message-read, message-search --query <text>
message-encode --text <text>, message-decode --hex <hex_bytes>
message-export-org --output <path>, message-import-org --file <path>
message-export-bundle --output <path> [--range <all|vanilla|expanded>]
message-import-bundle --file <path> [--apply] [--strict] [--range <all|vanilla|expanded>] [--project <path>] (expanded apply requires a project)
message-write --id <id> --text <text> --project <path>
message-export-bin --output <path> [--range expanded]
message-export-asm --output <path> [--range expanded]
dialogue-list, dialogue-read, dialogue-search --query <text>
hex-search --pattern <hex>

CLI Discovery Flow

Use scoped help directly from the CLI:

z3ed --help
z3ed dungeon
z3ed dungeon-place-sprite --help

Agent CLI

Agent commands are routed through the agent subcommand:

z3ed agent simple-chat --rom=zelda3.sfc
z3ed agent plan --rom=zelda3.sfc
z3ed agent run --rom=zelda3.sfc
z3ed agent diff --rom=zelda3.sfc
z3ed agent test replay tests/gui/recording.json --set room_id=0x12 --set input_text=hello

Use z3ed agent with no args for a full list of agent subcommands.

Mesen2 Live Debugging

These commands connect to a running Mesen2-OoS instance via the local socket (/tmp/mesen2-<pid>.sock). They do not require a ROM argument. The debug alias is the recommended front door (Mesen2 is the default backend).

`z3ed mesen-gamestate`

Read ALTTP game state from Mesen2.

Syntax:

z3ed mesen-gamestate [--format <json|text>]

Examples:

z3ed mesen-gamestate

z3ed debug state

`z3ed mesen-sprites`

List active sprites from Mesen2.

Syntax:

z3ed mesen-sprites [--all] [--format <json|text>]

Examples:

z3ed mesen-sprites

z3ed mesen-sprites --all

`z3ed mesen-cpu`

Read CPU register state.

Syntax:

z3ed mesen-cpu [--format <json|text>]

Examples:

z3ed mesen-cpu

`z3ed mesen-memory-read`

Read emulator memory.

Syntax:

z3ed mesen-memory-read --address <hex> [--length <n>] [--format <json|text>]

Examples:

z3ed mesen-memory-read --address 0x7E0020 --length 16

`z3ed mesen-memory-write`

Write emulator memory (hex bytes).

Syntax:

z3ed mesen-memory-write --address <hex> --data <hexbytes> [--format <json|text>]

Examples:

z3ed mesen-memory-write --address 0x7E0010 --data 01

`z3ed mesen-disasm`

Disassemble code at an address.

Syntax:

z3ed mesen-disasm --address <hex> [--count <n>] [--format <json|text>]

Examples:

z3ed mesen-disasm --address 0x008000 --count 20

`z3ed mesen-trace`

Fetch execution trace.

Syntax:

z3ed mesen-trace [--count <n>] [--format <json|text>]

Examples:

z3ed mesen-trace --count 50

`z3ed mesen-breakpoint`

Manage breakpoints.

Syntax:

Examples:

z3ed mesen-breakpoint --action add --address 0x008000

z3ed mesen-breakpoint --action clear

`z3ed mesen-control`

Control emulation state.

Syntax:

z3ed mesen-control --action <pause|resume|step|frame|reset>

Examples:

z3ed mesen-control --action pause

AI Integration

AI workflows are available via the z3ed agent commands (see Agent CLI).

Global Options

These options work with all commands:

--rom <file> - Specify ROM file to use
--sandbox - Run ROM commands against a sandbox copy
--format <json|text> - Output format
--data-format <hex|ascii|both> - Byte view for read commands
--tui / --interactive - Removed (use z3ed help and command-scoped --help)
--list-commands - List all available commands
--export-schemas - Export command schemas as JSON
--version - Show version information
--self-test - Run CLI self-test
--verbose - Enable verbose output
--quiet - Suppress non-error output
--ai_provider <name> - AI provider (auto, ollama, gemini, openai, anthropic, mock)
--ai_model <name> - Provider-specific model override
--gemini_api_key <key> - Gemini API key
--anthropic_api_key <key> - Anthropic API key
--ollama_host <url> - Ollama host URL
--openai_base_url <url> - OpenAI-compatible base URL (LM Studio: http://localhost:1234)
--gui_server_address <host:port> - GUI automation server
--prompt_version <name> - Prompt version override
--use_function_calling <true|false> - Enable Gemini function calling
--mesen-socket <path> - Override Mesen2 socket path
--help - Show help for command
--http-port <port> - HTTP API port (if enabled in build)
--http-host <host> - HTTP API display host (printed URLs only)

Environment variable shortcuts for AI providers: GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL/OPENAI_API_BASE, OLLAMA_HOST, OLLAMA_MODEL.

Exit Codes

0 - Success
1 - Error (invalid args, missing ROM, failed command)

	yaze 0.3.2 Link to the Past ROM Editor

Table of Contents

ROM Operations

z3ed rom read

z3ed rom write

z3ed rom info

z3ed rom diff

z3ed rom compare

z3ed rom validate

z3ed rom generate-golden

Editing Commands

Dungeon Commands

Overworld Commands

GUI Automation (requires GUI gRPC server)

Testing Commands

z3ed test-list

z3ed test-run

z3ed test-status

Resource & Search Commands

CLI Discovery Flow

Agent CLI

Mesen2 Live Debugging

z3ed mesen-gamestate

z3ed mesen-sprites

z3ed mesen-cpu

z3ed mesen-memory-read

z3ed mesen-memory-write

z3ed mesen-disasm

z3ed mesen-trace

z3ed mesen-breakpoint

z3ed mesen-control

AI Integration

Global Options

Exit Codes

`z3ed rom read`

`z3ed rom write`

`z3ed rom info`

`z3ed rom diff`

`z3ed rom compare`

`z3ed rom validate`

`z3ed rom generate-golden`

`z3ed test-list`

`z3ed test-run`

`z3ed test-status`

`z3ed mesen-gamestate`

`z3ed mesen-sprites`

`z3ed mesen-cpu`

`z3ed mesen-memory-read`

`z3ed mesen-memory-write`

`z3ed mesen-disasm`

`z3ed mesen-trace`

`z3ed mesen-breakpoint`

`z3ed mesen-control`