Command Line Interface

Command-Line Interface

FEBuilderGBA provides a cross-platform CLI (FEBuilderGBA.CLI) for automation and scripting.

Basic Usage

FEBuilderGBA.CLI [options]

Commands

Information

--version              # Show application version
--help                 # Show help message

ROM Operations

--lint --rom=rom.gba                                   # Run lint validation
--rebuild --rom=modified.gba --fromrom=original.gba    # Rebuild/defragment ROM
--makeups=patch.ups --rom=modified.gba [--fromrom=original.gba]  # Create UPS patch
--applyups=output.gba --rom=original.gba --patch=patch.ups       # Apply UPS patch

Text Export/Import

# Export all text to TSV
--rom=rom.gba --translate --out=texts.tsv

# Import text from TSV
--rom=rom.gba --translate --in=texts.tsv

# Validate round-trip (exit 0=lossless, 2=mismatches)
--translate-roundtrip --rom=rom.gba

Struct Data Export/Import

# Export a single table
--export-data --rom=rom.gba --table=units --out=units.tsv

# Export all tables
--export-data --rom=rom.gba --table=all --out=data

# Import data
--import-data --rom=rom.gba --table=units --in=units.tsv

# Validate round-trip
--data-roundtrip --rom=rom.gba --table=all

Available Tables

units, classes, items, portraits, sound_room, sound_boss_bgm, support_units, support_talks, support_attributes, event_haiku, event_battle_talk, event_force_sortie, worldmap_points, worldmap_paths, worldmap_bgm, map_settings, link_arena_deny, cc_branch, menu_definitions, item_weapon_triangle, map_exit_points, ai_map_settings, ai_perform_items, ai_perform_staff, ai_steal_items, ai_targets, generic_enemy_portraits, status_options, ed_retreat, ed_epithet, ed_epilogue_a, ed_epilogue_b, ed_epilogue_c, op_class_demo, op_class_font, op_prologue, class_alpha_names, summon_units, summons_demon_king, monster_probability

Graphics

--decreasecolor --in=input.png --out=output.png [--noScale] [--noReserve1stColor] [--ignoreTSA]

Other

--disasm=out.asm --rom=rom.gba                                      # Disassemble code to a file
--pointercalc --rom=source.gba --target=target.gba --address=0x12345  # Search pointer references across two ROMs
--songexchange --rom=dest.gba --fromrom=source.gba --fromsong=0x1A --tosong=0x1A  # Copy a song between ROMs
--convertmap1picture --in=map.png --outImg=tiles.bin --outTSA=tsa.bin  # Convert an image to map tiles + TSA

More commands

The CLI exposes 67 commands in total. Beyond the ones above, the major families are:

• ROM info / validation: --rom-info, --checksum, --repair-header, --diff, --lint-oam, --freespace, --hex-dump
• Graphics: --render-portrait, --export-portrait-all, --import-portrait(-all), --generate-font, --export-palette, --import-palette
• Audio: --export-midi, --import-midi
• Events / animation: --disasm-event, --compile-event, --export-battle-anime, --import-battle-anime
• Patches: --apply-patch, --uninstall-patch, --list-patches, --list-resources
• Data / text: --search-text, --text-refs, --export-map-settings, --list-tables, --resolve-names, --expand-table, --merge3, --lz77

Run FEBuilderGBA.CLI --help for the full list, or see docs/cli-reference.md for the per-command reference.

Decomp project mode

FEBuilderGBA can treat a decompilation source tree as the source of truth instead of a .gba binary. Open the project directory with --project=<dir>; the built ROM is loaded only as a read-only preview and edits are written back to the owning C struct / JSON source element. See Decomp Project Mode for the end-to-end workflow.

# Open a decomp project and show its mode badge / metadata
--rom-info --project=decomp/

# Resolve a ROM address to a source symbol (name / source artifact / offset)
--resolve-addr=0x08012345 --project=decomp/

# Advisory diff-to-source migration: classify built-vs-edited ROM changes
--migrate-diff --project=decomp/ --rom2=edited.gba --out=migrate.tsv

# Source-backed table write: rewrite the owning C/JSON element (not the ROM)
--write-source --project=decomp/ --table=items --id=1 --field=might --value=0x0A
--write-source --project=decomp/ --table=units --id=1 --field=hp --value=18 --field=pow --value=7

# Export a ROM asset into the source tree (palette / graphics / map / text)
--export-asset --kind=palette --rom=rom.gba --addr=0x5524 --out=gfx/palette.pal
--export-asset --kind=map --rom=rom.gba --addr=0x200000 --out=map/chapter1.mar

# Validate an import asset on disk (read-only — never mutates the ROM)
--validate-asset --kind=graphics --in=gfx/tiles.png

# Run the manifest build command (explicit opt-in via --yes) and reload
--build-project --project=decomp/ --reload --yes

# Print the round-trip coverage matrix (source-backed / exporter / preview / manual / ROM-only)
--decomp-audit --format=md --out=docs/decomp-coverage.md

# Bridge Nightmare .nmm table schemas <-> decomp manifest table defs
--nmm-to-manifest --in=items.nmm --table=items --out=items.tables.json
--manifest-to-nmm --project=decomp/ --table=items --out=items.nmm

Command	Purpose
--project=<dir>	Open a decomp project directory; load its built ROM as a preview (combine with other commands)
--resolve-addr=<hex>	Resolve an address to a project symbol (requires --project)
--migrate-diff	Classify built-vs-edited ROM changes (requires --project, --rom2; advisory / read-only)
--write-source	Rewrite the owning C/JSON source element (requires --project, --table, --id, --field/--value)
--export-asset	Export a ROM asset to a source-tree path (--kind=graphics|palette|map|text)
--validate-asset	Structurally validate an import asset on disk (never mutates the ROM)
--build-project	Run the manifest build command (gated behind --yes; optional --reload)
--decomp-audit	Print the decomp round-trip coverage matrix (no ROM)
--nmm-to-manifest / --manifest-to-nmm	Bridge Nightmare .nmm schemas ↔ manifest table defs

Android

There is no separate Android CLI — the Android port is a native GUI build of the Avalonia frontend. See Native Android and docs/ANDROID.md for building the APK. The CLI itself runs on any platform with the .NET 10 runtime.