<!-- 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 the routing table in your project instructions, 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, 48 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).
	search	discover Nexus candidates (names only) with version/date/status, marked have/have?/new against the registry; needs X4_NEXUS_KEY; does not change the registry
	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