X4 Cli Reference

---
name: x4-cli-reference
description: Use when you need the exact subcommands, flags, positional arguments or defaults of an X4 toolkit CLI (x4validate, x4modlist, x4compat, x4xref, x4stats, x4similar, x4effective, x4diff, x4debug, x4save, x4live), or before composing a command line for one instead of recalling a flag from memory.
---

<!-- GENERATED by tools/x4validate/scripts/gen-cli-reference.py from each CLI's own argparse help. Do not edit: regenerate. -->

# X4 toolkit CLI reference

The exact surface of every toolkit CLI, generated from its own argparse help so it cannot drift from the code. **Which tool answers which question** is CLAUDE.md's routing table, not this file.

Run a CLI from `$CLAUDE_PROJECT_DIR/tools/x4validate` as `uv run <cli> ...`. The full `--help` of a CLI and of each of its subcommands is in `reference/<cli>.md` -- read it before composing a command line.

11 CLIs, 47 subcommands.

| CLI | subcommand | what it does |
|---|---|---|
| **`x4compat`** | | Detect how the ENABLED (active) X4 mods collide over the effective XML tree -- the set the engine loads: on disk in any configured extensions root and enabled (the profile entry decides; the manifest's enabled= is only the default when the profile has none), with every required dependency loading. |
| | `check` | analyze collisions across the enabled (active) modlist |
| **`x4debug`** | | Triage the engine's debug.txt, and compare it to what we predicted. |
| | `triage` | bucket and attribute every [=ERROR=] line |
| | `crosscheck` | per-item diff of engine-skipped ops vs x4validate's prediction |
| | `baseline` | archive this log with a content fingerprint |
| **`x4diff`** | | Semantic XML diff between two mod versions. |
| **`x4effective`** | | Browse the effective merged values of every X4 entity, with provenance. |
| | `build` | (re)build the effective store |
| | `ls` | list entities of a kind |
| | `show` | all props + provenance for one entity |
| | `attr` | one prop across all entities of a class |
| | `who-sets` | provenance chain for an entity['s prop] |
| | `diff-mod` | every value a mod wins |
| | `dump` | live effective XML for ANY vpath (incl. md/, aiscripts/) |
| | `sql` | read-only SELECT against the store |
| | `coverage` | what this store DOES and does not index (so a negative can carry its denominator) |
| **`x4live`** | | Read what the running engine saw, out of the profile's uidata.xml, and diff it against our model. |
| | `dump` | what the probe captured, with its denominators |
| | `extensions` | the engine's extension list, diffed PER ITEM |
| | `errors` | the engine's own error log, as captured |
| | `oracle` | engine-resolved macro values vs the effective store |
| | `archive` | copy the dump OUT of uidata.xml, which X4 OVERWRITES on exit (ground truth has been lost this way once) |
| | `mappings` | DERIVE candidate field mappings from a dump or a groundtruth TSV (proposals only - never auto-applied) |
| | `query` | ask the RUNNING engine one question over the pipe |
| | `pausestate` | READ whether the running game is paused, and whether THIS channel made the pause. Changes nothing; the safe check after a lost write reply |
| | `pause` | WRITE: pause the running game. Refuses if it is already paused; exit 0 only when the engine reads back paused |
| | `unpause` | WRITE: undo a pause THIS channel made. Refuses anyone else's pause; exit 0 only when the engine reads back running |
| | `harvest` | ask the RUNNING engine EVERYTHING we can think to ask, in ONE connection, and write it down |
| | `ffi-census` | DISABLED BY DEFAULT (crash containment, F124): set X4_LIVE_ALLOW_FFI=1 to enable. Asks the RUNNING engine, name by name, whether it exports each C function vanilla's ui lua declares in ffi.cdef -- the surface `query globals` cannot see. Indexes ffi.C only: nothing is called or declared |
| | `groundtruth` | harvest the engine's DERIVED values live and WRITE THEM DOWN (the fixture any future traversal must reproduce) |
| | `ramp` | MEASURE the message-size cap. An over-long message does NOT truncate -- it TEARS THE PIPE DOWN, costing the whole connection (F74, corrected 2026-08-29). Bounded below at 64,000 bytes; the ceiling above that is unmeasured |
| **`x4modlist`** | | X4 mod-registry triage tool (API-first). |
| | `ingest` | scan installed extension folders (PRIMARY) into the registry, cross-checked against the profile content.xml |
| | `refresh` | refresh upstream metadata via Nexus/Steam API, and say which mods have an update: upstream's newest MAIN file uploaded more than 3 days after the installed manifest's date (both dates printed); an upload within that window reads same-release?, not available |
| | `dashboard` | regenerate WORKLIST.md from the registry |
| | `needs-review` | list entries needing a spot-check decision |
| | `resolve` | pin a mod's Nexus identity permanently (+fetch) |
| | `source` | record a non-Nexus origin (stops it being searched) |
| | `verify` | list identities that are guesses, with the denominator |
| | `tracked` | what the ACCOUNT tracks on Nexus vs what is INSTALLED |
| | `ignore` | mark a junk/personal mod out of the active worklist |
| | `mark` | mark a mod as custom-edited (for /x4-update-mod) |
| | `changed` | localise a moved content fingerprint: WHICH mod changed, and how |
| | `snapshot` | record the current mod vector as a cheap baseline (~0.1s), for the gap between expensive rebuilds |
| **`x4save`** | | Read an X4 savegame: what is baked into it, and what it references that the live tree no longer defines. |
| | `info` | header: build, playtime, and the SAVE-BAKED extensions |
| | `check` | macro references the live tree no longer defines |
| **`x4similar`** | | Advisory fuzzy same-ship detection across the ships base, DLC and installed mods define, scored at their EFFECTIVE values (base + DLC + the enabled mods in load order, so a <diff>-patched ship carries its patched numbers). |
| **`x4stats`** | | Advisory numeric comparison of mod content vs the effective game. |
| | `wares` | compare a candidate mod's wares to same-group peers |
| | `macro` | flatten a macro file's numeric property vector |
| **`x4validate`** | | Validate X4 mod diff patches against the effective merged game tree. |
| **`x4xref`** | | Cross-index of MD/aiscript actions, events, and cue edges. |
| | `build` | (re)build the index over base+DLC+installed mods |
| | `who-calls` | list every place an action element appears, cue-edge actions (signal_cue, cancel_cue, ...) included |
| | `who-listens` | list every cue reacting to an event_* condition |
| | `cue` | where a cue is defined, signalled, cancelled |