Configuration

Configuration

Select the game explicitly through --game, PX_GAME_ID or configuration. The profiles are ck3, vic3 and eu5; paths and capabilities belong to the selected profile.

Local configuration file

The CLI searches upward from its current directory for the nearest .px-toolkit/pxtk.json. Use --config <file> to select one directly. This minimal configuration deliberately disables game discovery and external validation:

{
  "game": "ck3",
  "gamePath": null,
  "logsPath": null,
  "tigerPath": null,
  "parents": [],
  "language": "english"
}

Replace null values with the actual game-data directory, generated script-documentation directory and Tiger executable when needed. A game installation root is accepted and normalized to its game folder. Omitting gamePath permits Steam discovery; explicit null disables it. Invalid explicit paths are reported and do not cause another installation to be chosen.

For a standard .px-toolkit/pxtk.json, relative paths resolve from the project folder above .px-toolkit. A config outside that directory uses its own containing folder. The editable mod defaults to that base folder. Paths in flags and environment variables resolve from the process working directory. Keep machine-specific configuration ignored by Git.

Settings and overrides

Flags take precedence over environment variables, then the config file. Repeated --parent flags provide the selected dependency list in load order, base first.

Setting	CLI option	Environment variable
Game profile	--game	PX_GAME_ID
Editable mod	--mod	PX_<GAME>_MOD_PATH
Game installation or data	--game-path	PX_<GAME>_GAME_PATH
Generated documentation	--logs-path	PX_<GAME>_LOGS_PATH
Tiger executable	--tiger	PX_<GAME>_TIGER_PATH
Explicit Tiger config	--tiger-config	PX_<GAME>_TIGER_CONFIG
Existing launcher user-data folder	--user-data-path	PX_<GAME>_USER_DATA_PATH
Dependency folders	repeated --parent	Use config parents
Localization language	--language	Use config language
Request/process timeout in seconds	--timeout	Use config timeout

Replace <GAME> with the uppercase profile ID, for example PX_CK3_GAME_PATH. Timeout defaults to 300 seconds; accepted config values are 1 to 3600 seconds. Config objects reject unknown fields.

Portable Toolkit settings

The CLI reads .px-toolkit/project.json, localization.json, schema.json and playset.json. Each artifact independently falls back to the game's legacy config folder. Invalid authoring rules are reported. The CLI does not read VS Code's private machinePaths registry.

project.json supplies authoring and diagnostic rules. localization.json supplies placement defaults and the language when CLI/config language is absent. Existing owned entries stay in place. New entries use configured destinations, meaningful siblings and established layouts. A prefix alone does not select a file. New vanilla localization overrides require a replace folder; generated localization must use its source workflow.

The mod's playset.json is an indexing overlay. Its parents follow configured parents. It is separate from the saved launcher playsets used by playsets and launch.

Tiger uses an explicit tigerConfig first, then a config in the Toolkit config directory, then the mod-root Tiger config. Existing Tiger configuration controls its own dependencies and suppressions, rather than receiving generated dependency blocks. Inspect it if Tiger's view differs from the CLI's declared parents.

Launcher prerequisites

playsets and launch need installed launcher-settings.json and existing engine load settings. Listing or selecting playsets also needs the launcher database and saved playsets. An alternate userDataPath can be inspected, but launch requires the canonical location from launcher metadata's gameDataPath. This setting does not redirect the engine's user directory.

Run pxtk status --json after changing configuration. A generated documentation dump is evidence of source content, not proof that it matches the installed game patch.