Getting Started

Getting started

Use Node 22.22.2 or newer and pnpm. No Toolkit checkout or VS Code installation is needed to run an installed CLI package.

Install from npm

Install the public npm package:

pnpm add -g pxtk-cli@0.2.1
pxtk --version
pxtk --help

If pxtk is absent from PATH, correct pnpm's global executable path or invoke node <installed-package>/dist/pxtk.cjs with the same arguments. Image preparation requires the package's optional native Sharp dependencies.

GitHub release archive

Download pxtk-cli-0.2.1.tgz and SHA256SUMS.txt from v0.2.1. After checking the archive's SHA-256 against the checksum file, install it:

pnpm add -g ./pxtk-cli-0.2.1.tgz

GitHub Packages

GitHub Packages distributes @jdeffner/pxtk-cli@0.2.1 with the same pxtk executable. GitHub requires a personal access token (classic) even for public packages. Use a token with read:packages. The npm install above avoids this authentication step.

With pnpm 11 or newer, try scoped registry login:

pnpm login --scope=@jdeffner --registry=https://npm.pkg.github.com

Use your GitHub username and the classic token as the password if prompted. If this login flow is unavailable, add these entries to your user-level ~/.npmrc, then supply GITHUB_PACKAGES_TOKEN through your session environment or secret manager. pnpm supports environment references in user-level auth files:

@jdeffner:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

Keep credentials out of project files. With the @jdeffner scope mapped to GitHub Packages, keep npm as the default registry for other dependencies and install:

pnpm add -g @jdeffner/pxtk-cli@0.2.1

Build from source

git clone --branch v0.2.1 https://github.com/JDeffner/paradox-toolkit-cli.git
cd paradox-toolkit-cli
pnpm install --frozen-lockfile
pnpm run compile
pnpm pxtk --help
pnpm pack --pack-destination .local/artifacts

Install the resulting tarball with pnpm add -g <tarball>, or continue using pnpm pxtk from the checkout. Builds use the pinned core archives in the repository and do not require a second source checkout.

Configure an existing mod

Select an existing saved mod and an explicit game. This PowerShell example previews configuration, displays it and applies the reviewed request:

$initArgs = @("init", "--game", "ck3", "--mod", "<existing-mod>", "--json")
$preview = pxtk @initArgs | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { throw "Preview failed." }
$preview.data.files | Format-List file, action, content
# Review the output before running this application command.
pxtk @initArgs --write --expect $preview.data.previewToken

Replace <existing-mod> with the actual mod folder. init creates .px-toolkit/pxtk.json without replacing existing configuration. Set game, documentation and Tiger paths through configuration. Keep local paths out of version control.

From the configured mod, begin with:

pxtk status --json
pxtk search add_gold --limit 20 --json
pxtk inspect add_gold --kind effect --json
pxtk read events/mymod_events.txt --json
pxtk validate --json

The identifier examples use CK3. Use identifiers returned by the selected profile for other games. Status shows which sources loaded and which checks are unavailable. Validation can be incomplete when Tiger or its required game data is missing.

Create a new mod

The destination must be absent or empty, and its parent must exist:

New-Item -ItemType Directory -Force .local/mods | Out-Null
$newArgs = @("new", ".local/mods/research-mod", "--name", "Research Mod", "--game", "ck3", "--json")
$preview = pxtk @newArgs | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { throw "Preview failed." }
$preview.data | ConvertTo-Json -Depth 8
# Review files, folders, supported version and nextSteps first.
pxtk @newArgs --write --expect $preview.data.previewToken

The destination resolves from the process working directory. Creation writes profile-derived metadata, configuration and folders. It does not register the mod with a launcher or change a playset. Follow nextSteps. If the installed version is unknown, the declared version defaults to *; review it before distribution.

Continue with Command Reference or MCP and Agents.