Repository navigation
Command Reference
Run pxtk --help for the installed command set. Add --json for the versioned result envelope. Commands below assume a configured saved mod unless they select a game directly.
| Command | Purpose and example |
|---|---|
status |
Loaded sources and missing capabilities: pxtk status --json
|
search <text> |
Bounded identifiers and definitions: pxtk search add_gold --limit 20 --json
|
inspect <name> |
Exact meaning and source evidence: pxtk inspect add_gold --kind effect --examples --templates --json
|
read <file> |
Saved source page: pxtk read events/mymod_events.txt --start-line 1 --line-count 100 --json
|
impact <name> |
Indexed callers and dependencies: pxtk impact my_effect --kind scripted_effect --json
|
validate [files...] |
Structural checks and whole-mod Tiger: pxtk validate events/mymod_events.txt --json
|
new <folder> |
New-mod preview: pxtk new .local/mods/research-mod --name "Research Mod" --game ck3 --json
|
init |
Existing-mod config preview: pxtk init --game ck3 --mod <existing-mod> --json
|
create [kind] [name] |
List profile templates or preview a scaffold: pxtk create event mymod.1 --prefix mymod --json
|
loc get/set/check |
Localization lookup, edit or coverage: pxtk loc set mymod_1_t --value "A title" --json
|
logs read/checkpoint |
Group saved errors or preview a checkpoint: pxtk logs checkpoint --output .px-toolkit/before-test.json --json
|
format <files...> |
Leading-indentation preview/check: pxtk format events/mymod_events.txt --check --json
|
image inspect/convert |
Inspect or prepare textures: pxtk image inspect art/icon.png --json
|
playsets |
Saved playsets and profile presets: pxtk playsets --game ck3 --json
|
launch |
Literal game-launch preview: pxtk launch --game ck3 --playset "<ID-or-unique-name>" --arg=-debug_mode --json
|
pxtk mcp starts the stdio server. It is not a separate MCP tool. Preparation details are on Editing and Localization; client setup is on MCP and Agents.
These workflows are included in the 0.2.0 package.
| Workflow | Example |
|---|---|
| Translation synchronization | pxtk loc sync --source-language english --language german --json |
| Symbol rename | pxtk rename --file common/scripted_effects/mymod.txt --line 1 --column 1 --to mymod_new_effect --json |
| Precise definition edits | pxtk edit --file common/traits/mymod.txt --operations edits.json --json |
| Ordered mod conflicts | pxtk conflicts --input <base-mod> --input <later-mod> --limit 50 --json |
| Exact vanilla import | pxtk import --source common/scripted_effects/<file>.txt --json |
| Local release directory | pxtk package --output <new-release-folder> --json |
| Migration review | pxtk migrate catalog --game ck3 --json |
See editing, conflicts/import/packaging and migrations for the write and coverage contracts.
Operation results share schemaVersion: 1, operation, status, data, sources and warnings. Execution errors instead return {schemaVersion:1,status:"error",error:{code,message}}. Read the result fields even when the process exits successfully. Lists report totals and truncation; --limit accepts 1 to 200 and defaults to 20. A bounded list is not the complete inventory.
Help and version metadata are smaller JSON objects: pxtk --version --json returns {schemaVersion:1,version}, and pxtk --help --json adds help. They are not operation envelopes.
| Exit | Meaning |
|---|---|
| 0 | Completed without new errors |
| 1 | New errors, no match, ambiguity or report findings requiring review |
| 2 | Invalid input/configuration, unavailable checks, cancellation or execution failure |
Warnings remain visible and do not alone set exit 1. Conflict reports use exit 1 for overlaps or composition issues, including identical overlaps.
Inspect excerpts are bounded to 18 lines and 500 characters per line. They report omissions and clipped lines. Use continuation with MCP pxtk_read, or read the file directly:
$page = pxtk read events/mymod_events.txt --line-count 100 --max-chars 16000 --json | ConvertFrom-Json
$page.data.text
if ($page.data.next) {
pxtk read $page.data.file --start-line $page.data.next.startLine --start-column $page.data.next.startColumn --source-hash $page.data.sourceHash --json
}Continue with both next.startLine and next.startColumn until next is null. Concatenate data.text, not display context. Positions are 1-based UTF-16 columns. Pages preserve decoded line endings and omit the UTF-8 BOM; sourceHash covers saved bytes. A changed hash rejects continuation. Default budgets are 100 lines and 16,000 characters, with maxima of 200 and 64,000. Files must be supported text under configured source roots and at most 16 MiB.
pxtk validate --write-baseline .px-toolkit/before-change.json --json
# Make and save the intended changes.
pxtk validate --baseline .px-toolkit/before-change.json --jsonBaseline creation is explicitly authorized by --write-baseline; it does not use --write. The destination must be a new JSON file in an existing directory inside the mod. Relative paths are mod-relative. Creation requires complete validation. Comparison retains repeated findings while ignoring line movement. It rejects changed game/version, validator, schema, documentation, language, configuration, dependencies or structural file selection. Do not recreate a baseline to hide errors introduced by a change.
Selected files focus structural checks only. Tiger still checks the whole mod. Known-unsupported Tiger versions, missing Tiger and failed Tiger make validation incomplete; findings remain visible. complete: true does not certify patch support or gameplay.
Preview the executable, working directory, literal arguments and engine load settings. Repeat the same request with --start --expect <previewToken> to launch. Launch uses --start, not --write. Put CLI options before -- when passing extra game arguments after it. Use only presets returned by playsets.
An explicit playset applies enabled mods in saved order and disabled DLC to the engine load file. The launcher database and its active selection stay unchanged. Without a playset, launch preserves the current engine load file, which can differ from the launcher selection. Changed load files are backed up; failed startup restores them only if that does not overwrite a later edit. Stale tokens and an already-running game reject startup before load settings change. The process result is a one-second observation, not proof that the mod loaded.