One command, your local game

Start from the repository

twf dev
twf dev --port 4310

The CLI finds the nearest boardengine.json, using its entry, optional named export, and assets directory. Discovery stops at a package or Git repository boundary. Without a config, it uses that package’s src/game.ts. Invalid configuration fails explicitly.

twf dev --config configs/local.json
twf dev src/another-game.ts --export game

Paths inside a config are relative to that JSON file. An explicit module is relative to the current directory. Choose a config or a module, not both. Local development requires no platform login.

Put the repository’s CLI on PATH

New projects include .envrc. With direnv installed and its shell hook enabled, approve that file once:

pnpm install
direnv allow
twf --version
twf dev

The file adds node_modules/.bin to PATH. It uses the CLI installed by this repository’s lockfile, including when you enter a child directory. It does not install packages or change versions when you enter the directory. Without direnv, pnpm exec twf dev does the same job.

Work on the latest engine source

The engine repository has its own .envrc, which exposes scripts/bin/twf. That shim runs the CLI TypeScript source in the current checkout, so CLI edits take effect on the next invocation without building or reinstalling a global package.

To use that source CLI from an independent game repository, add this to the game’s ignored .envrc.local:

PATH_add /absolute/path/to/boardengine/scripts/bin

Install dependencies in the engine checkout first. Run direnv allow after creating the override, then check command -v twf. This selects the source CLI while the game continues to load its own installed SDK. Testing an unreleased SDK is a separate, deliberate dependency change; it can be installed from an SDK tarball produced by pnpm release:pack in the engine checkout.

Upgrade the published CLI deliberately

pnpm add -D --save-exact @tabletopwithfriends/cli@latest
twf --version
twf dev

Review and commit the package and lockfile changes. latest selects the newest published CLI when you run the install command; the saved dependency becomes exact. For an older compatibility line, use a tag such as @tabletopwithfriends/cli@sdk-0.1, or an exact release number. The SDK remains pinned independently. Unsupported host APIs fail with instructions to use the matching CLI.