x4cat

A Linux/cross-platform CLI and Python library for working with X4: Foundations .cat/.dat archives.

Egosoft’s X Catalog Tool is Windows-only. x4cat is a pure-Python reimplementation with additional modding tooling built for Linux and macOS.

Quick install

uv tool install git+https://github.com/meethune/x4cat.git

Verify it works:

x4cat --help

Command	Description
`list` (alias `ls`)	List files inside `.cat/.dat` archives with glob and regex filtering
`extract` (alias `x`)	Extract files to disk, preserving directory structure and timestamps
`pack`	Pack loose files into a `.cat/.dat` catalog pair
`diff`	Compare two directories and pack only changed/added files

Command	Description
`xmldiff`	Generate an X4-compatible `<diff>` patch from two XML files
`validate-diff`	Validate diff patches against base game files, checking XPath selectors
`check-conflicts`	Detect conflicts between multiple mods’ overlapping diff patches
`validate-schema`	Validate MD/AI scripts against indexed schema rules (fast, no XSD compilation)

Command	Description
`index`	Build a SQLite index of game wares, macros, and components
`inspect`	Look up any asset by ware ID, macro name, or component name
`search`	Search assets by partial match across IDs, groups, and tags
`extract-macro`	Extract a macro file by ID, resolving its path through the index

Command	Description
`scaffold ware`	Generate boilerplate for a new trade ware (diff patch + translation file)
`scaffold equipment`	Clone an existing engine/weapon/shield and generate all required files
`scaffold ship`	Clone an existing ship macro with index registration and ware entry
`scaffold translation`	Generate a translation stub for a new language from an existing file
`validate-translations`	Check that all text references have matching translation entries
`init`	Scaffold a complete mod project from a template with Makefile, tests, and CI