@idlekit/cli

idk is the command-line interface for idle game design evaluation. Use it to validate scenarios, run simulations, inspect pacing, compare variants, and tune strategies. Official support in v1: Bun >=1.4.2 only. Node.js and browser runtimes are not part of the v1 compatibility contract.

This registry install requires a published package. If it returns 404, use the repository local-pack workflow, including its overrides for unpublished internal dependencies, in a separate consumer project.

bun add -g @idlekit/cli

Requires Bun >=1.4.2.

Typical flow:

idk init scenario --track personal --preset builder --out ./my-game-v1.json --name "Space Miner"
idk validate ./space-miner-v1.json
idk simulate ./space-miner-v1.json --format json
idk experience ./space-miner-v1.json --format json
idk evaluate ./space-miner-v1.json --format md

Interactive scaffold and review:

idk init scenario --wizard true --track personal --preset builder --out ./my-game-v1.json
idk review doctor
idk review evaluate ./space-miner-v1.json
idk review compare ./space-miner-v1.json ./space-miner-v1-compare-b.json
idk tune ./space-miner-v1.json --wizard true
idk experiment ./experiment-spec.json

Shell completion and health check:

source <(idk completions zsh)
idk doctor --format md
idk doctor --fix true --shell zsh
idk review doctor
idk setup plugin-trust --plugin ./custom-econ-plugin.ts --out ./.idk/plugin-trust.json

Worked real-game example in this repository:

bun run --cwd packages/cli dev -- experience ../../examples/tutorials/14-orbital-foundry-v1.json \
  --plugin ../../examples/plugins/custom-econ-plugin.ts \
  --allow-plugin true \
  --session-pattern twice-daily \
  --days 7 \
  --format json

Large monetary values

compare, tune and balance support --engine breakInfinity, alongside the existing simulation commands. Number remains the default; scenario.engine does not choose the runtime. Use the explicit flag when scenario amounts exceed Number's range, and use engine operations in custom models and objectives.

Construct plugin amounts with the supplied ctx.E. When adapting a game that uses its own Decimal library, convert amounts through decimal text with ctx.E.from(text) at the boundary, including costs, rewards and returned state. Separate game SDK and CLI bundles can contain different Decimal constructors.

idk compare ./a.json ./b.json --engine breakInfinity --metric endNetWorth
idk tune ./a.json --tune ./tune.json --engine breakInfinity
idk balance ./workflow.json --engine breakInfinity --format md

Compare preserves monetary text, while tuning objectives such as endNetWorthLog10 produce finite logarithmic scores. Replay artifacts retain the selected engine. Balance supports decimal-string currency targets and results; CSV parameter edits, time/count metrics and sensitivity knobs remain finite Numbers. See the balance guide for target syntax and engine-specific freshness checks. breakEternity remains experimental.

Runtime

@idlekit/cli is maintained as a Bun-first CLI package.

• automation path: evaluate, compare --format json, experience --format md|json
• human review path: review evaluate, review compare, review doctor
• guided setup path: init scenario --wizard, tune --wizard, doctor --fix, setup completions
• recommended human sequence: init scenario --wizard -> review doctor -> review evaluate -> review compare -> tune --wizard

Documentation

• Repository: github.com/imjlk/idlekit
• Product roadmap: docs/roadmap.md
• Start here: docs/start-here-cli-designer.md
• Command reference: docs/usage-guide.md
• Typed CSV balance workflow: docs/balance-sheets.md